@plur-ai/mcp 0.1.1 → 0.2.1

package/README.md

@@ -1,36 +1,39 @@
 # @plur-ai/mcp
 
-MCP server for PLUR — exposes persistent AI memory as Model Context Protocol tools.
+MCP server for PLUR — gives any AI agent persistent memory via the Model Context Protocol.
+
+```bash
+npx @plur-ai/mcp
+```
+
+Or install globally:
 
 ```bash
 npm install -g @plur-ai/mcp
 ```
 
-The `plur-mcp` binary is now in your PATH. Point any MCP client at it and your agent has memory.
+## Setup
 
-## Configuration
+### Claude Code
 
-### Claude Code (`.mcp.json`)
+Add to `.claude/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "plur": {
-      "command": "plur-mcp"
-    }
+    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
   }
 }
 ```
 
-### Cursor (`.cursor/mcp.json`)
+### Cursor
+
+Add to `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "plur": {
-      "command": "plur-mcp",
-      "args": []
-    }
+    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
   }
 }
 ```
@@ -41,7 +44,8 @@ The `plur-mcp` binary is now in your PATH. Point any MCP client at it and your a
 {
   "mcpServers": {
     "plur": {
-      "command": "plur-mcp",
+      "command": "npx",
+      "args": ["-y", "@plur-ai/mcp"],
       "env": { "PLUR_PATH": "/path/to/storage" }
     }
   }
@@ -52,27 +56,36 @@ The `plur-mcp` binary is now in your PATH. Point any MCP client at it and your a
 
 | Tool | Description |
 |------|-------------|
-| `plur.learn` | Create an engram — record a reusable learning, preference, or correction |
-| `plur.recall` | Query engrams by keyword/phrase — retrieve relevant learned knowledge |
-| `plur.inject` | Get scored context for a task — directives and considerations within token budget |
-| `plur.feedback` | Rate an engram's usefulness — trains injection relevance over time |
-| `plur.forget` | Retire an engram — marks it inactive without deleting history |
-| `plur.capture` | Append an episode to the timeline — records what happened in a session |
-| `plur.timeline` | Query past episodes — filter by time, agent, channel, or search |
-| `plur.ingest` | Extract engram candidates from content using pattern matching |
-| `plur.packs.install` | Install an engram pack from a directory path |
-| `plur.packs.list` | List all installed engram packs |
-| `plur.status` | System health — engram count, episode count, pack count, storage root |
+| `plur.learn` | Store a memory — correction, preference, convention, or decision |
+| `plur.recall` | Keyword search (BM25, instant) |
+| `plur.recall.hybrid` | **Best default** — BM25 + embeddings merged via RRF. No API calls. |
+| `plur.inject` | Select engrams for current task within token budget |
+| `plur.feedback` | Rate an engram — trains injection relevance over time |
+| `plur.forget` | Retire a memory (history preserved) |
+| `plur.capture` | Record a session event to the episodic timeline |
+| `plur.timeline` | Query past episodes by time, agent, or search |
+| `plur.ingest` | Extract engram candidates from text |
+| `plur.sync` | Git-based sync across machines |
+| `plur.sync.status` | Check sync state (initialized, remote, dirty, ahead/behind) |
+| `plur.packs.install` | Install an engram pack |
+| `plur.packs.list` | List installed packs |
+| `plur.status` | System health — engram count, episodes, packs, storage root |
+
+## How agents use it
+
+**Session start:** Call `plur.inject` with the task description to load relevant memory.
+
+**When corrected:** Call `plur.learn` to store the correction.
 
-## How to Use (as the AI agent)
+**Session end:** Call `plur.capture` to record what happened.
 
-At session start: call `plur.inject` with your task description to load relevant memory into context.
+**Rate results:** Call `plur.feedback` on injected engrams to improve future quality.
 
-When the user corrects you: call `plur.learn` to record it.
+**Cross-device:** Call `plur.sync` with a git remote URL to sync memory across machines.
 
-At session end: call `plur.capture` to record what happened.
+## Update notifications
 
-Rate injected engrams with `plur.feedback` to improve future injection quality.
+The server checks npm on startup and logs a warning if a newer version is available. No overhead during operation — the check runs once, asynchronously.
 
 ## License
 

package/dist/index.js

@@ -4,7 +4,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { Plur } from "@plur-ai/core";
+import { Plur, checkForUpdate } from "@plur-ai/core";
 
 // src/tools.ts
 function getToolDefinitions() {
@@ -71,6 +71,41 @@ function getToolDefinitions() {
         };
       }
     },
+    {
+      name: "plur.recall.hybrid",
+      description: "Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion. No API calls, fully local. Best default for most use cases.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query to find relevant engrams" },
+          scope: { type: "string", description: "Filter by scope (also includes global)" },
+          domain: { type: "string", description: "Filter by domain prefix" },
+          limit: { type: "number", description: "Max results to return (default 20)" },
+          min_strength: { type: "number", description: "Minimum retrieval strength (0-1)" }
+        },
+        required: ["query"]
+      },
+      handler: async (args, plur) => {
+        const results = await plur.recallHybrid(args.query, {
+          scope: args.scope,
+          domain: args.domain,
+          limit: args.limit,
+          min_strength: args.min_strength
+        });
+        return {
+          results: results.map((e) => ({
+            id: e.id,
+            statement: e.statement,
+            type: e.type,
+            scope: e.scope,
+            domain: e.domain,
+            retrieval_strength: e.activation.retrieval_strength
+          })),
+          count: results.length,
+          mode: "hybrid"
+        };
+      }
+    },
     {
       name: "plur.inject",
       description: "Get a scored context injection for a task \u2014 returns directives and considerations within token budget",
@@ -264,6 +299,34 @@ function getToolDefinitions() {
         };
       }
     },
+    {
+      name: "plur.sync",
+      description: "Sync engrams via git \u2014 initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          remote: {
+            type: "string",
+            description: "Git remote URL (e.g. git@github.com:user/plur-engrams.git). Only needed on first call to set up remote."
+          }
+        }
+      },
+      handler: async (args, plur) => {
+        const result = plur.sync(args.remote);
+        return result;
+      }
+    },
+    {
+      name: "plur.sync.status",
+      description: "Check git sync status \u2014 whether repo is initialized, has remote, is dirty, ahead/behind counts",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      },
+      handler: async (_args, plur) => {
+        return plur.syncStatus();
+      }
+    },
     {
       name: "plur.status",
       description: "Return system health \u2014 engram count, episode count, pack count, storage root",
@@ -285,11 +348,17 @@ function getToolDefinitions() {
 }
 
 // src/server.ts
+var VERSION = "0.2.1";
 async function createServer(plur) {
   const instance = plur ?? new Plur();
   const tools = getToolDefinitions();
+  checkForUpdate("@plur-ai/mcp", VERSION, (r) => {
+    if (r.updateAvailable) {
+      console.error(`[plur] Update available: ${r.current} \u2192 ${r.latest}. Run: npx @plur-ai/mcp@latest`);
+    }
+  });
   const server = new Server(
-    { name: "plur-mcp", version: "0.1.0" },
+    { name: "plur-mcp", version: VERSION },
     { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -12,7 +12,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.1.1"
+    "@plur-ai/core": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"