### Quick Start Guide

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

A quick guide to get started with the most common Plur CLI commands.

```APIDOC
## Quick Start

Initialize Plur for automatic memory injection:

```bash
plur init
```

Store a new memory (engram):

```bash
plur learn "Always validate user input at API boundaries"
```

Search for memories:

```bash
plur recall "validation"
```

Get relevant context for a task:

```bash
plur inject "fix the auth bug"
```

List all stored engrams:

```bash
plur list
```

Provide feedback on an engram:

```bash
plur feedback ENG-2026-0329-001 positive
```

Retire an outdated engram:

```bash
plur forget ENG-2026-0329-001
```
```

--------------------------------

### Development Setup and Build

Source: https://github.com/plur-ai/plur/blob/main/README.md

Commands to clone the PLUR AI repository, install dependencies, build the project, and run tests.

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

```

--------------------------------

### Installation

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Instructions on how to install the Plur AI CLI globally or use it without installation.

```APIDOC
## Installation

Install the Plur AI CLI globally using npm:

```bash
npm install -g @plur-ai/cli
```

Alternatively, you can use it without installing via `npx`:

```bash
npx @plur-ai/cli status
```
```

--------------------------------

### Install and Configure Plugin

Source: https://github.com/plur-ai/plur/blob/main/packages/claw/README.md

Install the package via npm and add it to your plugins configuration to enable automatic memory.

```bash
npm install @plur-ai/claw
```

```json
{
  "plugins": ["@plur-ai/claw"]
}
```

--------------------------------

### Global Install and Initialize PLUR MCP

Source: https://github.com/plur-ai/plur/blob/main/README.md

Installs the PLUR MCP globally for faster startup and initializes its configuration.

```bash
npm install -g @plur-ai/mcp
plur-mcp init
```

--------------------------------

### OpenClaw Plugin Configuration File Example

Source: https://context7.com/plur-ai/plur/llms.txt

Example JSON configuration for enabling the `@plur-ai/claw` plugin and specifying MCP server command and arguments.

```json
{
  "plugins": ["@plur-ai/claw"],
  "mcpServers": {
    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
  }
}
```

--------------------------------

### Install plur-hermes

Source: https://github.com/plur-ai/plur/blob/main/packages/hermes/README.md

Install the plugin via pip to enable auto-discovery by the Hermes Agent on startup.

```bash
pip install plur-hermes
```

--------------------------------

### Install @plur-ai/core

Source: https://github.com/plur-ai/plur/blob/main/packages/core/README.md

Install the core package using npm. This is the first step to integrating persistent memory into your AI agent.

```bash
npm install @plur-ai/core
```

--------------------------------

### Install and Configure OpenClaw PLUR Plugin

Source: https://github.com/plur-ai/plur/blob/main/README.md

Installs the PLUR plugin for OpenClaw and enables its functionality.

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

--------------------------------

### Install @plur-ai/cli Globally

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Install the Plur CLI globally using npm for command-line access.

```bash
npm install -g @plur-ai/cli
```

--------------------------------

### Install MCP Server for Claude Code

Source: https://context7.com/plur-ai/plur/llms.txt

Installs the MCP server for Claude Code, setting up storage, configuration, and hooks. Can be installed via npx or globally.

```bash
npx @plur-ai/mcp init
```

```bash
npm install -g @plur-ai/mcp
plur-mcp init
```

--------------------------------

### Plur CLI Command: Install Pack

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `packs install` command to install an engram pack from a specified source.

```bash
plur packs install "https://github.com/user/repo.git"
```

--------------------------------

### MCP Server Configuration

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Example configuration for integrating the PLUR MCP server locally.

```json
{
  "mcpServers": {
    "plur": {
      "command": "node",
      "args": ["packages/mcp/dist/index.js"],
      "env": { "PLUR_PATH": "/tmp/plur-test" }
    }
  }
}
```

--------------------------------

### JSON Output Example with Piping

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Demonstrates how Plur CLI output is automatically JSON when piped, and how to extract specific fields using `jq`.

```bash
# Human-readable
plur recall "testing"

# JSON (piped)
plur recall "testing" | jq '.results[0].statement'
```

--------------------------------

### Publishing Packages

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Commands to publish packages to the registry, starting with the core dependency.

```bash
pnpm --filter @plur-ai/core publish --access public --no-git-checks
pnpm --filter @plur-ai/mcp publish --access public --no-git-checks
pnpm --filter @plur-ai/claw publish --access public --no-git-checks
```

--------------------------------

### Start MCP Session

Source: https://context7.com/plur-ai/plur/llms.txt

Initializes a session and injects relevant engrams based on the provided task.

```json
// Request
{
  "tool": "plur_session_start",
  "arguments": {
    "task": "Fix the authentication bug in the login flow"
  }
}

// Response
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "engrams": {
    "text": "## DIRECTIVES\n[ENG-001] Always use bcrypt for password hashing...",
    "count": 5,
    "injected_ids": ["ENG-001", "ENG-002", "ENG-003"]
  },
  "store_stats": {
    "engram_count": 156,
    "episode_count": 42,
    "pack_count": 3
  },
  "guide": "Session started with 5 engrams from 156 total..."
}
```

--------------------------------

### Run @plur-ai/cli Without Installation

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Execute Plur CLI commands without a global installation using npx.

```bash
npx @plur-ai/cli status
```

--------------------------------

### Quick Start with Plur Memory

Source: https://github.com/plur-ai/plur/blob/main/packages/core/README.md

Initialize Plur, learn from agent corrections, recall information using hybrid search, inject memories into prompts, provide feedback, and sync across machines.

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

const plur = new Plur()

// Your agent gets corrected — save it
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 } = plur.inject('Write tests for the user service', {
  scope: 'project:my-app',
  budget: 2000
})

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

// Sync across machines via git
plur.sync('git@github.com:you/plur-memory.git')
```

--------------------------------

### plur_session_start

Source: https://context7.com/plur-ai/plur/llms.txt

Starts a new session and injects relevant engrams based on the provided task description.

```APIDOC
## plur_session_start

### Description
Starts a session and injects relevant engrams for the task. Call at the beginning of every conversation.

### Request Body
- **task** (string) - Required - The task description to find relevant engrams for.

### Request Example
{
  "tool": "plur_session_start",
  "arguments": {
    "task": "Fix the authentication bug in the login flow"
  }
}

### Response
#### Success Response (200)
- **session_id** (string) - Unique identifier for the session.
- **engrams** (object) - Contains injected text, count, and list of IDs.
- **store_stats** (object) - Statistics about the current store.
- **guide** (string) - Summary of the session initialization.

#### Response Example
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "engrams": {
    "text": "## DIRECTIVES\n[ENG-001] Always use bcrypt for password hashing...",
    "count": 5,
    "injected_ids": ["ENG-001", "ENG-002", "ENG-003"]
  },
  "store_stats": {
    "engram_count": 156,
    "episode_count": 42,
    "pack_count": 3
  },
  "guide": "Session started with 5 engrams from 156 total..."
}
```

--------------------------------

### Manage Knowledge Packs

Source: https://context7.com/plur-ai/plur/llms.txt

Installs, lists, exports, and uninstalls curated engram packs.

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

const plur = new Plur()

// Install a pack
const installResult = plur.installPack('/path/to/react-patterns-pack')
// Returns: { installed: true, name: 'react-patterns', conflicts: [] }

// List installed packs
const packs = plur.listPacks()
// Returns: [
//   { name: 'react-patterns', manifest: { version: '1.0.0', ... }, engram_count: 25, integrity: 'sha256:...' }
// ]

// Export engrams as a pack
const exportResult = plur.exportPack(
  plur.list({ domain: 'dev/testing' }),  // Engrams to export
  '~/plur-packs/testing-best-practices', // Output directory
  {
    name: 'testing-best-practices',
    version: '1.0.0',
    description: 'Testing conventions and patterns',
    creator: 'Your Name'
  }
)
// Returns: { path: '...', engram_count: 15, integrity: 'sha256:...', privacy: { clean: true, issues: [] } }

// Uninstall a pack
plur.uninstallPack('react-patterns')
```

--------------------------------

### Plur CLI Command: Init

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `init` command to install Claude Code hooks for automatic memory injection.

```bash
plur init
```

--------------------------------

### Quick Start: Initialize Plur and Manage Engrams

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Initialize Claude Code hooks for automatic memory injection, store new learnings, search memories, inject relevant context for tasks, list all engrams, provide feedback on engrams, and retire outdated knowledge.

```bash
# Install Claude Code hooks (automatic memory injection)
plur init

# Store a learning
plur learn "Always validate user input at API boundaries"

# Search memories
plur recall "validation"

# Get relevant context for a task
plur inject "fix the auth bug"

# List all engrams
plur list

# Give feedback (trains what surfaces next time)
plur feedback ENG-2026-0329-001 positive

# Retire outdated knowledge
plur forget ENG-2026-0329-001
```

--------------------------------

### Plur CLI JSON Output Options

Source: https://context7.com/plur-ai/plur/llms.txt

Examples of how to pipe Plur CLI output to `jq` for JSON processing or force JSON output using the `--json` flag.

```bash
plur recall "testing" | jq '.results[0].statement'

plur recall "testing" --json
```

--------------------------------

### Plur CLI Command: List Packs

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `packs list` command to display installed engram packs.

```bash
plur packs list
```

--------------------------------

### GET /recall

Source: https://context7.com/plur-ai/plur/llms.txt

Search for stored engrams using the BM25 algorithm.

```APIDOC
## GET /recall

### Description
Performs a fast, local keyword-based search to retrieve relevant engrams.

### Parameters
#### Query Parameters
- **query** (string) - Required - Search keywords.
- **scope** (string) - Optional - Filter by scope.
- **domain** (string) - Optional - Filter by domain prefix.
- **limit** (number) - Optional - Max results to return (default: 20).
- **min_strength** (number) - Optional - Minimum retrieval strength (0-1).

### Response
#### Success Response (200)
- **results** (array) - List of matching engrams sorted by relevance.
```

--------------------------------

### Plur Pack CLI Commands

Source: https://context7.com/plur-ai/plur/llms.txt

CLI commands for managing packs, including listing, installing, and exporting engrams as packs with specified domains and tags.

```bash
plur packs list

plur packs install /path/to/pack

plur packs export my-patterns --domain dev/patterns --tags react,hooks
```

--------------------------------

### Initialize Plur Instance

Source: https://context7.com/plur-ai/plur/llms.txt

Create a new Plur instance to manage memory storage. The system defaults to ~/.plur/ but supports custom paths.

```APIDOC
## Initialize Plur Instance

### Description
Initializes the memory engine. You can specify a custom storage path via the constructor or the PLUR_PATH environment variable.

### Parameters
#### Request Body
- **path** (string) - Optional - Custom file system path for storing engrams.

### Request Example
```typescript
const plur = new Plur({ path: '/custom/storage/path' });
```
```

--------------------------------

### Development Commands

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Standard commands for building and testing the monorepo from the root directory.

```bash
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Initialize and Use PLUR Core

Source: https://github.com/plur-ai/plur/blob/main/README.md

Demonstrates basic operations including learning, hybrid recall, context injection, feedback, event capture, timeline querying, and synchronization.

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

const plur = new Plur()

// Learn from a correction
plur.learn('toEqual() in Vitest is strict — use toMatchObject() for partial matching', {
  type: 'correction',
  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
const { engrams } = plur.inject('Write tests for the user service', {
  scope: 'project:my-app',
  limit: 15
})

// Feedback trains the system
plur.feedback(engram.id, 'positive')

// Capture an event (episode)
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
plur.sync('git@github.com:you/plur-memory.git')
```

--------------------------------

### Initialize @plur-ai/mcp for Claude Code

Source: https://github.com/plur-ai/plur/blob/main/packages/mcp/README.md

Run this command to automatically set up storage, MCP configuration, and hooks for Claude Code.

```bash
npx @plur-ai/mcp init
```

--------------------------------

### Plur Sync CLI Commands

Source: https://context7.com/plur-ai/plur/llms.txt

CLI commands for initializing synchronization with a remote repository and performing subsequent syncs.

```bash
plur sync --remote git@github.com:you/plur-memory.git

plur sync
```

--------------------------------

### Running Unit Tests

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Commands for executing the test suite across the entire project or for specific files.

```bash
pnpm test                                    # all packages
pnpm test -- packages/core/test/sync.test.ts # specific file
```

--------------------------------

### plur_inject_hybrid Request and Response

Source: https://context7.com/plur-ai/plur/llms.txt

Use plur_inject_hybrid to get relevant engrams formatted for task context injection. The response includes directives, considerations, and metadata about the injection.

```json
{
  "tool": "plur_inject_hybrid",
  "arguments": {
    "task": "Write unit tests for the payment service",
    "budget": 1500,
    "scope": "project:backend"
  }
}

{
  "directives": "[ENG-001] Always mock external payment APIs\n[ENG-002] Test both success and failure paths",
  "consider": "[ENG-010] Consider testing currency conversion edge cases",
  "count": 3,
  "tokens_used": 450,
  "injected_ids": ["ENG-001", "ENG-002", "ENG-010"],
  "mode": "hybrid"
}
```

--------------------------------

### Get Plur System Status

Source: https://context7.com/plur-ai/plur/llms.txt

Retrieve system health information, including engram and episode counts, storage path, and configuration details. This provides an overview of the Plur system's current state.

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

const plur = new Plur()

const status = plur.status()
// Returns:
// {
//   engram_count: 156,
//   episode_count: 42,
//   pack_count: 3,
//   storage_root: '/Users/you/.plur',
//   config: { index: true, injection_budget: 2000, ... }
// }
```

--------------------------------

### Configure PlurContextEngine

Source: https://github.com/plur-ai/plur/blob/main/packages/claw/README.md

Customize memory storage paths, automatic learning behavior, and token budgets by initializing the engine.

```typescript
import { PlurContextEngine } from '@plur-ai/claw'

new PlurContextEngine({
  path: '/custom/storage/path',  // default: ~/.plur/
  auto_learn: true,              // extract learnings automatically (default: true)
  auto_capture: true,            // record episodic summaries (default: true)
  injection_budget: 2000,        // token budget for engram injection (default: 2000)
})
```

--------------------------------

### Plur CLI Command: Sync

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `sync` command for cross-device synchronization via git.

```bash
plur sync
```

--------------------------------

### JSON Output Configuration

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

How to configure and utilize JSON output from the Plur CLI.

```APIDOC
## JSON Output

Output is automatically JSON when piped to other commands. You can also force JSON output using the `--json` flag.

```bash
# Human-readable output
plur recall "testing"

# JSON output (when piped)
plur recall "testing" | jq '.results[0].statement'

# Force JSON output
plur recall "testing" --json
```
```

--------------------------------

### Plur CLI Commands

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

A comprehensive list of all available commands for the Plur AI CLI.

```APIDOC
## Commands

| Command | Description |
|---|---|
| `plur learn <statement>` | Create a new engram |
| `plur recall <query>` | Search engrams (hybrid: BM25 + embeddings) |
| `plur inject <task>` | Get relevant engrams for a task (three-tier output) |
| `plur list` | List all engrams with optional filtering |
| `plur forget <id>` | Retire an engram |
| `plur feedback <id> <signal>` | Rate an engram (positive/negative/neutral) |
| `plur capture <summary>` | Record an episode to the timeline |
| `plur timeline [query]` | Query the episodic timeline |
| `plur status` | System health check |
| `plur sync` | Cross-device sync via git |
| `plur packs list` | List installed engram packs |
| `plur packs install <source>` | Install an engram pack |
| `plur init` | Install Claude Code hooks for automatic injection |
```

--------------------------------

### Plur Store CLI Commands

Source: https://context7.com/plur-ai/plur/llms.txt

CLI commands for managing team stores, including adding a store with a specified path and scope, and listing all configured stores.

```bash
plur stores add ~/team/engrams.yaml --scope team:backend

plur stores list
```

--------------------------------

### PLUR Package Overview

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

List of the three primary packages within the PLUR monorepo.

```text
@plur-ai/core   — engram engine (learn, recall, inject, search, decay, sync)
@plur-ai/mcp    — MCP server (Claude Code, Cursor, Windsurf)
@plur-ai/claw   — OpenClaw ContextEngine plugin
```

--------------------------------

### Package Dependency Structure

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Visual representation of package dependencies.

```text
@plur-ai/core  ←  @plur-ai/mcp
               ←  @plur-ai/claw
```

--------------------------------

### Plur CLI Command: Learn

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `learn` command to create a new engram with a given statement.

```bash
plur learn "Always validate user input at API boundaries"
```

--------------------------------

### Initialize Plur Instance

Source: https://context7.com/plur-ai/plur/llms.txt

Creates a new Plur instance to interact with the memory system. You can specify a custom storage path or rely on the default.

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

// Default storage path: ~/.plur/
const plur = new Plur()

// Custom storage path
const plurCustom = new Plur({ path: '/custom/storage/path' })

// Or set via environment variable
// PLUR_PATH=/custom/path node app.js
```

--------------------------------

### Run LongMemEval Benchmark

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Command to execute the LongMemEval retrieval accuracy benchmark.

```bash
# From a memorybench checkout (not in this repo)
PLUR_SEARCH_MODE=hybrid python run.py --provider plur
```

--------------------------------

### Add MCP Server for Explicit Tools

Source: https://github.com/plur-ai/plur/blob/main/packages/claw/README.md

Include the MCP server in your configuration to provide agents with on-demand memory tools like plur.learn and plur.recall.

```json
{
  "mcpServers": {
    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
  },
  "plugins": ["@plur-ai/claw"]
}
```

--------------------------------

### Plur CLI Command: Capture

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `capture` command to record an episode to the timeline with a given summary.

```bash
plur capture "User reported a bug in the login process."
```

--------------------------------

### POST /learn

Source: https://context7.com/plur-ai/plur/llms.txt

Store a new engram (correction, preference, or convention) into the memory system.

```APIDOC
## POST /learn

### Description
Stores a statement as an engram. The system automatically assigns an ID, activation strength, and timestamp.

### Parameters
#### Request Body
- **statement** (string) - Required - The knowledge to store.
- **type** (string) - Optional - Category: behavioral, terminological, procedural, or architectural.
- **scope** (string) - Optional - Contextual scope (e.g., global, project:name).
- **domain** (string) - Optional - Hierarchical domain tag.
- **source** (string) - Optional - Origin of the knowledge.
- **tags** (array) - Optional - List of relevant keywords.
- **rationale** (string) - Optional - Explanation for the knowledge.
- **visibility** (string) - Optional - Access level: private, public, or template.
- **knowledge_anchors** (array) - Optional - References to specific file paths or code snippets.
- **dual_coding** (object) - Optional - Supplemental examples or analogies.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the engram.
- **statement** (string) - The stored knowledge.
- **scope** (string) - The assigned scope.
```

--------------------------------

### Configure MCP for Cursor

Source: https://github.com/plur-ai/plur/blob/main/packages/mcp/README.md

Add this configuration to your .cursor/mcp.json file to enable the plur MCP server.

```json
{
  "mcpServers": {
    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
  }
}
```

--------------------------------

### Basic Plur CLI Commands

Source: https://context7.com/plur-ai/plur/llms.txt

Common Plur CLI commands for managing learnings, searching memories, injecting context, listing engrams, providing feedback, retiring engrams, and checking status.

```bash
plur init

plur learn "Always use semantic versioning for API releases"

plur recall "versioning"

plur recall "versioning" --fast

plur inject "release the new API version"

plur list

plur list --scope project:backend --domain dev

plur feedback ENG-2026-0401-001 positive

plur forget ENG-2026-0401-001

plur status
```

--------------------------------

### Sync Memory via Git

Source: https://github.com/plur-ai/plur/blob/main/packages/mcp/README.md

Use the plur_sync tool to synchronize memory across different machines using a git remote.

```text
Agent: plur_sync({ remote: "git@github.com:you/plur-memory.git" })
→ "Initialized and pushed."

# On another machine, same remote:
Agent: plur_sync()
→ "Synced. Pulled 12 remote commits."
```

--------------------------------

### Plur Episode CLI Commands

Source: https://context7.com/plur-ai/plur/llms.txt

CLI commands for capturing episodes and querying the timeline, with options for filtering by agent and date.

```bash
plur capture "Deployed v2.3.0 to production successfully"

plur timeline

plur timeline --agent claude-code --since 2026-04-01
```

--------------------------------

### POST plur_sync

Source: https://context7.com/plur-ai/plur/llms.txt

Synchronizes engrams via git to share across devices.

```APIDOC
## POST plur_sync

### Description
Sync engrams via git to share across devices.

### Method
POST

### Request Body
- **remote** (string) - Optional - Git remote URL for initialization.
```

--------------------------------

### PLUR AI Storage Configuration

Source: https://github.com/plur-ai/plur/blob/main/README.md

Details the default storage location for PLUR AI data and how to enable the optional SQLite read index for performance.

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

```

--------------------------------

### Configure MCP Server

Source: https://context7.com/plur-ai/plur/llms.txt

Defines the MCP server configuration for Plur, including optional environment variables for storage paths.

```json
{
  "mcpServers": {
    "plur": {
      "command": "npx",
      "args": ["-y", "@plur-ai/mcp"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "plur": {
      "command": "npx",
      "args": ["-y", "@plur-ai/mcp"],
      "env": {
        "PLUR_PATH": "/custom/storage/path"
      }
    }
  }
}
```

--------------------------------

### Sync Engrams via Git with Plur SDK

Source: https://context7.com/plur-ai/plur/llms.txt

Sync engrams across machines using Git. The first call initializes the repository and sets the remote. Subsequent calls commit and push/pull changes. `plur.syncStatus()` checks the sync status without making changes.

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

const plur = new Plur()

// First call: initialize and set remote
const initResult = plur.sync('git@github.com:you/plur-memory.git')
// Returns: { status: 'initialized', message: 'Initialized and pushed.' }

// Subsequent calls: sync changes
const syncResult = plur.sync()
// Returns: { status: 'synced', pulled: 5, pushed: 3, message: 'Synced. Pulled 5 commits.' }

// Check sync status without making changes
const status = plur.syncStatus()
// Returns: {
//   initialized: true,
//   has_remote: true,
//   is_dirty: false,
//   ahead: 2,
//   behind: 0,
//   remote: 'git@github.com:you/plur-memory.git'
// }
```

--------------------------------

### Learning Protocol Format

Source: https://github.com/plur-ai/plur/blob/main/packages/hermes/plur_hermes/skills/plur-memory.SKILL.md

Use this format at the end of responses to allow the plugin to auto-capture reusable insights.

```text
---
🧠 I learned:
- Insight one (min 10 characters)
- Insight two
```

--------------------------------

### Synchronization and Storage API

Source: https://github.com/plur-ai/plur/blob/main/packages/core/README.md

APIs for managing memory synchronization across machines and understanding storage details.

```APIDOC
## Synchronization and Storage API

### Description
APIs for managing memory synchronization across machines and understanding storage details.

### Methods

#### `sync(remote?)`

- **Description**: Synchronizes memory across machines using Git. If a remote is specified, it pushes/pulls from that remote.
- **Parameters**:
  - `remote` (string) - Optional - The Git remote URL (e.g., 'git@github.com:you/plur-memory.git').

#### `syncStatus()`

- **Description**: Checks the current synchronization status without making any changes.

### Storage

- **Description**: Plur memory is stored as plain YAML files, allowing for easy reading, editing, and versioning.
- **Default Location**: `~/.plur/`
- **Files**: `engrams.yaml`, `episodes.yaml`, `candidates.yaml`, `config.yaml`, `packs/`
- **Customization**: The storage location can be overridden using the `PLUR_PATH` environment variable or by providing a `path` option during `Plur` instantiation: `new Plur({ path: '...' })`.
```

--------------------------------

### How Plur Works

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

An explanation of the underlying mechanism of Plur's engram storage and retrieval.

```APIDOC
## How It Works

Engrams are stored locally as plain YAML files in `~/.plur/`. The search functionality is entirely offline, utilizing a combination of BM25 keyword matching and BGE-small embeddings with Reciprocal Rank Fusion. No API calls or cloud services are involved, ensuring offline functionality.

The `--fast` flag optimizes search by disabling the embedding model, relying solely on BM25. This is beneficial for scripts and automation where speed is prioritized over semantic similarity.
```

--------------------------------

### OpenClaw Plugin Configuration

Source: https://context7.com/plur-ai/plur/llms.txt

TypeScript configuration for the PlurContextEngine in the OpenClaw plugin, allowing customization of storage path, auto-learning, auto-capture, and injection budget.

```typescript
import { PlurContextEngine } from '@plur-ai/claw'

const engine = new PlurContextEngine({
  path: '/custom/storage/path',  // default: ~/.plur/
  auto_learn: true,              // extract learnings automatically (default: true)
  auto_capture: true,            // record episodic summaries (default: true)
  injection_budget: 2000,        // token budget for engram injection (default: 2000)
})
```

--------------------------------

### plur_sync for Cross-Device Synchronization

Source: https://context7.com/plur-ai/plur/llms.txt

Sync engrams across devices using plur_sync via git. Initialize with a remote repository URL or perform subsequent syncs without specifying the remote.

```json
{
  "tool": "plur_sync",
  "arguments": {
    "remote": "git@github.com:you/plur-memory.git"
  }
}

{
  "tool": "plur_sync",
  "arguments": {}
}
```

--------------------------------

### AI Agent Integration

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Information on how the Plur CLI integrates with various AI agents and tools.

```APIDOC
## Use with AI Agents

The CLI serves as a universal bridge for AI agent integrations. It is utilized by:

- **[plur-hermes](https://pypi.org/project/plur-hermes/)**: Hermes Agent plugin (auto-installs via npx if not found).
- **[@plur-ai/mcp](https://www.npmjs.com/package/@plur-ai/mcp)**: MCP server for Claude Code, Cursor, Windsurf.
- **[@plur-ai/claw](https://www.npmjs.com/package/@plur-ai/claw)**: OpenClaw plugin.
```

--------------------------------

### POST plur_session_end

Source: https://context7.com/plur-ai/plur/llms.txt

Ends a session, captures learnings, and records an episode to the timeline.

```APIDOC
## POST plur_session_end

### Description
End a session, capture learnings, and record an episode to the timeline.

### Method
POST

### Request Body
- **summary** (string) - Required - Summary of the session.
- **session_id** (string) - Required - Unique session identifier.
- **engram_suggestions** (array) - Required - List of new engrams to create.
```

--------------------------------

### Inject Context

Source: https://context7.com/plur-ai/plur/llms.txt

Selects and formats the most relevant engrams for a given task within a specified token budget, returning directives, constraints, and considerations.

```APIDOC
## Inject Context

### Description
Selects and formats relevant engrams for a specific task, considering a token budget. Returns structured context including directives, constraints, and considerations.

### Method
`inject(task: string, options?: InjectOptions)`
`injectHybrid(task: string, options?: InjectHybridOptions)`

### Parameters
#### Path Parameters
- **task** (string) - Required - The description of the task for which context is needed.

#### Query Parameters
- **options** (object) - Optional - Configuration options for context injection.
  - **budget** (number) - Optional - The maximum token budget for the injected context (default: 2000).
  - **scope** (string) - Optional - Filters engrams by a specific scope (e.g., 'project:backend').

### Request Example
```typescript
// Basic injection
const result = plur.inject('Write tests for the user authentication service')

// With options
const scoped = plur.inject('Deploy the new feature', {
  budget: 2000,
  scope: 'project:backend'
})

// Hybrid injection (recommended)
const hybrid = await plur.injectHybrid('Refactor the payment module', {
  budget: 1500,
  scope: 'service:payments'
})
```

### Response
#### Success Response (200)
- **directives** (string) - Instructions or commands.
- **constraints** (string) - Limitations or rules to follow.
- **consider** (string) - Points to consider or be aware of.
- **count** (number) - The number of engrams selected.
- **tokens_used** (number) - The total tokens used by the injected context.
- **injected_ids** (Array<string>) - The IDs of the engrams that were injected.

#### Response Example
```json
{
  "directives": "[ENG-001] Always mock external services\n[ENG-002] Test edge cases first",
  "constraints": "[ENG-005] Never test against production database",
  "consider": "[ENG-010] Consider using test fixtures for user data",
  "count": 5,
  "tokens_used": 450,
  "injected_ids": ["ENG-001", "ENG-002", "ENG-005", "ENG-010"]
}
```
```

--------------------------------

### Configure Custom Storage Path

Source: https://github.com/plur-ai/plur/blob/main/packages/mcp/README.md

Define a custom storage path for memory by setting the PLUR_PATH environment variable in your MCP configuration.

```json
{
  "mcpServers": {
    "plur": {
      "command": "npx",
      "args": ["-y", "@plur-ai/mcp"],
      "env": { "PLUR_PATH": "/path/to/storage" }
    }
  }
}
```

--------------------------------

### Configure Multi-Store Knowledge Sharing

Source: https://context7.com/plur-ai/plur/llms.txt

Adds and lists external engram stores to enable team-wide knowledge sharing with namespaced IDs.

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

const plur = new Plur()

// Add a team store
plur.addStore('~/projects/my-team/engrams.yaml', 'team:backend', {
  shared: true,      // Git-committed, team-visible
  readonly: true     // Cannot modify via this instance
})

// List all stores
const stores = plur.listStores()
// Returns:
// [
//   { path: '~/.plur/engrams.yaml', scope: 'global', shared: false, readonly: false, engram_count: 50 },
//   { path: '~/projects/my-team/engrams.yaml', scope: 'team:backend', shared: true, readonly: true, engram_count: 120 }
// ]

// Engrams from stores automatically appear in search/inject with namespaced IDs
// Store ID: ENG-2026-0401-001 → Namespaced: ENG-BCK-2026-0401-001
```

--------------------------------

### Plur CLI Command: List Engrams

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `list` command to display all engrams, with optional filtering capabilities.

```bash
plur list
```

--------------------------------

### Sync — Git-Based Sync

Source: https://context7.com/plur-ai/plur/llms.txt

Synchronizes engrams across machines via Git, handling initialization and remote operations.

```APIDOC
## Sync Engrams

### Description
Sync engrams across machines via git.

### Method
plur.sync(remote_url)

### Parameters
- **remote_url** (string) - Optional - The Git remote URL for initialization.
```

--------------------------------

### Rebuild Core Package

Source: https://github.com/plur-ai/plur/blob/main/CLAUDE.md

Command to rebuild the core package, required before running tests for dependent packages like Claw.

```bash
pnpm --filter @plur-ai/core build
```

--------------------------------

### Plur CLI Command: Timeline Query

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `timeline` command to query the episodic timeline, optionally with a specific query.

```bash
plur timeline "authentication issues"
```

--------------------------------

### POST plur_inject_hybrid

Source: https://context7.com/plur-ai/plur/llms.txt

Retrieves relevant engrams formatted for injection into a task context based on task description, budget, and scope.

```APIDOC
## POST plur_inject_hybrid

### Description
Get relevant engrams formatted for injection into a task context.

### Method
POST

### Request Body
- **task** (string) - Required - The task description.
- **budget** (integer) - Required - Token budget for injection.
- **scope** (string) - Required - The project scope.

### Request Example
{
  "tool": "plur_inject_hybrid",
  "arguments": {
    "task": "Write unit tests for the payment service",
    "budget": 1500,
    "scope": "project:backend"
  }
}

### Response
#### Success Response (200)
- **directives** (string) - Formatted injection directives.
- **consider** (string) - Additional considerations.
- **count** (integer) - Number of engrams returned.
- **tokens_used** (integer) - Total tokens consumed.
- **injected_ids** (array) - List of engram IDs.
- **mode** (string) - Injection mode used.
```

--------------------------------

### Inject Context for Tasks

Source: https://context7.com/plur-ai/plur/llms.txt

Selects and formats relevant engrams based on a task description. Supports token budgeting and hybrid injection methods.

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

const plur = new Plur()

// Basic injection
const result = plur.inject('Write tests for the user authentication service')
// Returns:
// {
//   directives: '[ENG-001] Always mock external services\n[ENG-002] Test edge cases first',
//   constraints: '[ENG-005] Never test against production database',
//   consider: '[ENG-010] Consider using test fixtures for user data',
//   count: 5,
//   tokens_used: 450,
//   injected_ids: ['ENG-001', 'ENG-002', 'ENG-005', 'ENG-010', ...]
// }

// With options
const scoped = plur.inject('Deploy the new feature', {
  budget: 2000,              // Token budget (default: 2000)
  scope: 'project:backend'   // Scope filter
})

// Hybrid injection with embeddings (recommended)
const hybrid = await plur.injectHybrid('Refactor the payment module', {
  budget: 1500,
  scope: 'service:payments'
})
```

--------------------------------

### Plur CLI Storage Details

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Engrams are stored as plain YAML files in `~/.plur/`. Search is performed locally using BM25 keyword matching and BGE-small embeddings with Reciprocal Rank Fusion, requiring no API calls or cloud services.

```bash
# Example of engram storage location
# ~/.plur/engrams.yaml
```

--------------------------------

### PLUR AI Project Structure

Source: https://github.com/plur-ai/plur/blob/main/README.md

Overview of the PLUR AI project's directory structure and core modules.

```tree
@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 (CLI subprocess bridge)

```

--------------------------------

### Core Memory Operations API

Source: https://github.com/plur-ai/plur/blob/main/packages/core/README.md

This section details the primary methods for interacting with the Plur memory system, including learning, recalling, and managing engrams.

```APIDOC
## Core Memory Operations API

### Description
Provides methods to interact with the Plur memory system for learning, recalling, and managing knowledge engrams.

### Methods

#### `learn(statement, context?)`

- **Description**: Stores an engram (correction, preference, convention, decision) into memory.
- **Parameters**:
  - `statement` (string) - Required - The knowledge statement to be stored.
  - `context` (object) - Optional - Additional context for the engram, such as `type`, `scope`, `domain`.

#### `recall(query, options?)`

- **Description**: Performs a BM25 keyword search for relevant engrams. This is an instant, zero-cost lookup.
- **Parameters**:
  - `query` (string) - Required - The search query.
  - `options` (object) - Optional - Additional options for the search.

#### `recallSemantic(query, options?)`

- **Description**: Performs a search based on semantic meaning using local embeddings. Typically takes ~200ms.
- **Parameters**:
  - `query` (string) - Required - The search query.
  - `options` (object) - Optional - Additional options for the search.

#### `recallHybrid(query, options?)`

- **Description**: Combines BM25 and semantic search using Reciprocal Rank Fusion (RRF). This is the recommended default search method and typically takes ~200ms.
- **Parameters**:
  - `query` (string) - Required - The search query.
  - `options` (object) - Optional - Additional options for the search.

#### `recallAsync(query, { llm })`

- **Description**: Performs an LLM-assisted semantic filtering search. Typically takes ~1s and involves one LLM call.
- **Parameters**:
  - `query` (string) - Required - The search query.
  - `llm` (object) - Required - An object containing the LLM configuration.

#### `recallExpanded(query, { llm })`

- **Description**: Expands the query and performs an exhaustive retrieval using hybrid search and LLM assistance. Typically takes ~3s and involves 3-5 LLM calls.
- **Parameters**:
  - `query` (string) - Required - The search query.
  - `llm` (object) - Required - An object containing the LLM configuration.

#### `inject(task, options?)`

- **Description**: Selects the most relevant engrams for a given task within a specified token budget.
- **Parameters**:
  - `task` (string) - Required - The task description.
  - `options` (object) - Optional - Options including `scope` and `budget`.

#### `feedback(id, signal)`

- **Description**: Provides feedback on the usefulness of a recalled engram, which helps train the injection relevance over time.
- **Parameters**:
  - `id` (string) - Required - The ID of the engram to provide feedback on.
  - `signal` (string) - Required - The feedback signal (e.g., 'positive', 'negative').

#### `forget(id, reason?)`

- **Description**: Retires an engram from active memory. History is preserved.
- **Parameters**:
  - `id` (string) - Required - The ID of the engram to forget.
  - `reason` (string) - Optional - The reason for forgetting the engram.

```

--------------------------------

### Plur CLI Command: Status

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `status` command to perform a system health check.

```bash
plur status
```

--------------------------------

### Plur CLI Global Flag: Path Override

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `--path <dir>` flag to override the default storage path for engrams.

```bash
plur --path "/custom/plur/storage" recall "data"
```

--------------------------------

### Plur CLI Command: Inject

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `inject` command to retrieve relevant engrams for a given task, providing a three-tier output.

```bash
plur inject "fix the auth bug"
```

--------------------------------

### Plur Memory Storage Structure

Source: https://github.com/plur-ai/plur/blob/main/packages/core/README.md

Understand the default storage location for PLUR data, which includes engrams, episodes, candidates, and configuration. The location can be overridden.

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

--------------------------------

### Feedback for Relevance

Source: https://context7.com/plur-ai/plur/llms.txt

Allows users to train the relevance of engrams by providing feedback. Positive feedback increases retrieval strength, while negative feedback decreases it.

```APIDOC
## Feedback for Relevance

### Description
Provides feedback on the relevance of specific engrams to help train the retrieval system. This feedback adjusts the retrieval strength of the engrams.

### Method
`feedback(engramId: string, feedbackType: 'positive' | 'negative' | 'neutral')`

### Parameters
#### Path Parameters
- **engramId** (string) - Required - The unique identifier of the engram to provide feedback on.
- **feedbackType** (string) - Required - The type of feedback: 'positive', 'negative', or 'neutral'.

### Request Example
```typescript
// Positive feedback: Engram was helpful
plur.feedback('ENG-2026-0401-001', 'positive')

// Negative feedback: Engram was not relevant
plur.feedback('ENG-2026-0401-002', 'negative')

// Neutral feedback: Track interaction without adjusting strength
plur.feedback('ENG-2026-0401-003', 'neutral')
```

### Effect
- **Positive feedback**: Increases retrieval_strength by 0.05 (capped at 1.0).
- **Negative feedback**: Decreases retrieval_strength by 0.1 (minimum 0.0).
- **Neutral feedback**: Records the interaction without modifying retrieval strength.
```

--------------------------------

### PLUR Directory Structure

Source: https://context7.com/plur-ai/plur/llms.txt

This outlines the standard directory structure for PLUR, including the location of engrams, episodes, configuration, and optional indexes.

```plaintext
~/.plur/
├── engrams.yaml     # learned knowledge (source of truth)
├── episodes.yaml    # session timeline
├── candidates.yaml  # pending engrams awaiting promotion
├── config.yaml      # settings
├── engrams.db       # optional SQLite read index (auto-generated)
└── packs/           # installed engram packs

```

--------------------------------

### Plur CLI Command: Recall

Source: https://github.com/plur-ai/plur/blob/main/packages/cli/README.md

Use the `recall` command to search engrams using a query. Supports hybrid search (BM25 + embeddings).

```bash
plur recall "validation"
```