persyst-mcp 1.0.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zayn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 **Local-first MCP memory server for coding agents.**
 
-Persyst gives AI coding agents (Claude Code, Cursor, Aider, Windsurf) persistent memory across sessions. It stores memories in a local SQLite database with hybrid keyword + semantic search — no cloud, no API keys, works offline.
+Persyst gives AI coding agents (Claude Code, Cursor, VS Code, Aider, Windsurf, Antigravity) persistent memory across sessions. It stores memories in a local SQLite database with hybrid keyword + semantic search — no cloud, no API keys, works offline.
 
 ## How It Works
 
@@ -14,59 +14,96 @@ Your AI Agent ←→ MCP (stdio) ←→ Persyst ←→ SQLite (local)
 2. **Agent searches memories** → Persyst finds matches by both keywords AND meaning
 3. **"dark mode" ↔ "night theme"** → Semantic search understands synonyms
 
-## Quick Start
+> 🚨 **First-Run Note**: On the first start, Persyst will automatically download the local embedding model (`all-MiniLM-L6-v2` ~50MB). This can take 30-60 seconds depending on your connection. The server will log `Loading embedding model...` and then proceed normally.
 
-### 1. Install
+---
 
-```bash
-npm install -g persyst-mcp
-```
+## Quick Start
 
-### 2. Add to Claude Code
+You don't need to install anything globally. You can run it instantly using `npx`:
 
-Edit your Claude Code MCP config (`claude_desktop_config.json`):
+### 1. Add to Claude Code or Claude Desktop
 
+#### Claude Code (CLI)
+Add this to your global configuration file located at `~/.claude.json`:
 ```json
 {
   "mcpServers": {
     "persyst": {
-      "command": "persyst-mcp"
+      "command": "npx",
+      "args": ["-y", "persyst-mcp"]
     }
   }
 }
 ```
 
-### 3. Use It
-
-In Claude Code, the agent can now call tools like:
-- `add_memory` — Store a fact
-- `search_memories` — Find relevant memories
-- `get_memory` — Get a specific memory
-- `update_memory` — Update a memory
-- `delete_memory` — Remove a memory
-- `get_recent_memories` — Latest memories
-- `get_important_memories` — Most important memories
+#### Claude Desktop
+Add this to your Claude Desktop configuration file:
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+* **Linux**: `~/.config/Claude/claude_desktop_config.json`
 
-## Setup for Other Agents
+```json
+{
+  "mcpServers": {
+    "persyst": {
+      "command": "npx",
+      "args": ["-y", "persyst-mcp"]
+    }
+  }
+}
+```
 
-### Cursor
+---
 
-Add to your Cursor MCP settings:
+## Setup for Other Agents
 
+### VS Code (Cline / Roo Code)
+Add this configuration to your user settings under the MCP settings file (`cline_mcp_settings.json`):
 ```json
 {
-  "persyst": {
-    "command": "persyst-mcp"
+  "mcpServers": {
+    "persyst": {
+      "command": "npx",
+      "args": ["-y", "persyst-mcp"]
+    }
   }
 }
 ```
 
-### Aider
+### Cursor
+Add Persyst in Cursor under **Settings → Features → MCP**:
+1. Click **+ Add New MCP Server**
+2. Name: `persyst`
+3. Type: `stdio`
+4. Command: `npx -y persyst-mcp`
 
+### Aider
+Start Aider from the command line passing the server command:
 ```bash
-# Start the MCP server alongside Aider
-persyst-mcp &
+aider --mcp-server persyst:npx -y persyst-mcp
 ```
+Or append this to your `.aider.conf.yml` project file:
+```yaml
+mcp-server:
+  - name: persyst
+    command: npx -y persyst-mcp
+```
+
+### Antigravity
+Add Persyst to your Antigravity agent configuration file at `~/.gemini/antigravity/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "persyst": {
+      "command": "npx",
+      "args": ["-y", "persyst-mcp"]
+    }
+  }
+}
+```
+
+---
 
 ## Available Tools
 
@@ -76,10 +113,12 @@ persyst-mcp &
 | `search_memories` | Hybrid keyword + semantic search | `query` (string), `limit` (number) |
 | `get_memory` | Get memory by ID | `id` (number) |
 | `update_memory` | Update memory content | `id` (number), `content` (string) |
-| `delete_memory` | Delete a memory | `id` (number) |
+| `delete_memory` | Delete a memory and clean up edges | `id` (number) |
 | `get_recent_memories` | Get latest memories | `limit` (number) |
 | `get_important_memories` | Get by importance score | `limit` (number) |
 
+---
+
 ## How Search Works
 
 Persyst uses **hybrid search** — combining two strategies:
@@ -89,28 +128,7 @@ Persyst uses **hybrid search** — combining two strategies:
 
 Results from both are merged. Keyword matches get a score boost so exact matches rank higher, but semantic matches still surface related memories.
 
-## Architecture
-
-```
-persyst/
-├── index.js              ← Entry point (starts MCP server)
-├── src/
-│   ├── server.js         ← MCP server (stdio transport)
-│   ├── database.js       ← SQLite + schema + CRUD
-│   ├── search.js         ← Hybrid search engine
-│   ├── embeddings.js     ← Local embedding generation
-│   └── tools.js          ← 7 MCP tool definitions
-├── test/
-│   └── smoke.js          ← End-to-end test
-└── db/                   ← Database files (gitignored)
-```
-
-## Data Storage
-
-- Database location: `~/.persyst/persyst.db`
-- All data stays on your machine
-- No telemetry, no cloud calls, no API keys
-- Works offline (airplane mode ✓)
+---
 
 ## Tech Stack
 
@@ -121,21 +139,26 @@ persyst/
 - **Embeddings:** @huggingface/transformers + all-MiniLM-L6-v2 (384-dim, ~50MB)
 - **Protocol:** MCP over stdio
 
-## Development
+---
 
-```bash
-# Clone and install
-git clone <repo-url>
-cd persyst
-npm install
+## Troubleshooting
 
-# Run smoke test
-npm test
+#### `better-sqlite3` installation fails
+`better-sqlite3` compiles native C++ code on installation. Make sure you have python and C++ build tools installed on your system:
+* **Windows:** Run `npm install --global windows-build-tools` or install Visual Studio Build Tools.
+* **macOS/Linux:** Run `xcode-select --install` or install `build-essential`.
 
-# Start server directly
-node index.js
-```
+#### The agent is stuck or loading forever on startup
+This is normal on the **very first run** because Persyst is downloading the ~50MB embedding model. Wait 30-60 seconds for it to complete. The next runs will be instant.
+
+#### Command not found: `persyst-mcp`
+Instead of running it globally, prefer using the `npx -y persyst-mcp` command in your agent configurations. It automatically installs and updates the server non-interactively.
+
+#### Permission Denied
+Do not run `npx` with `sudo`. If you run into permission issues, ensure your npm global prefix is owned by your user account.
+
+---
 
 ## License
 
-MIT
+MIT License. See [LICENSE](LICENSE) for details.

package/index.js

@@ -14,4 +14,7 @@
 
 import { startServer } from './src/server.js';
 
-startServer();
+await startServer().catch(err => {
+  console.error('❌ Persyst failed to start:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "persyst-mcp",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Local-first MCP memory server with hybrid keyword + semantic search for coding agents",
   "type": "module",
   "main": "index.js",
   "bin": {
     "persyst-mcp": "index.js"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "start": "node index.js",
     "test": "node test/smoke.js",
@@ -20,7 +29,12 @@
     "ai",
     "agents",
     "semantic-search",
-    "knowledge-graph"
+    "knowledge-graph",
+    "claude-code",
+    "cursor",
+    "aider",
+    "windsurf",
+    "memory-server"
   ],
   "author": "Zayn",
   "license": "MIT",

package/src/attestation.js

@@ -0,0 +1,206 @@
+/**
+ * attestation.js — Cryptographic Attestation Engine
+ * 
+ * Implements Ed25519 signature generation and verification for search queries.
+ * Chains each attestation by linking to the hash of the previous one.
+ */
+
+import crypto from 'crypto';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import db, { getLastAttestation, insertAttestation, getAttestationById } from './database.js';
+
+const KEYS_DIR = join(homedir(), '.persyst', 'keys');
+
+/**
+ * Initialize keypair if it doesn't already exist.
+ */
+export function initializeKeys() {
+  mkdirSync(KEYS_DIR, { recursive: true });
+  const pubPath = join(KEYS_DIR, 'public.pem');
+  const privPath = join(KEYS_DIR, 'private.pem');
+
+  if (!existsSync(pubPath) || !existsSync(privPath)) {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+    });
+    writeFileSync(pubPath, publicKey);
+    writeFileSync(privPath, privateKey);
+    console.error('[persyst] Generated new Ed25519 keypair for attestation');
+  }
+}
+
+/**
+ * Read private key.
+ */
+function getPrivateKey() {
+  const privPath = join(KEYS_DIR, 'private.pem');
+  return readFileSync(privPath, 'utf8');
+}
+
+/**
+ * Read public key.
+ */
+export function getPublicKey() {
+  const pubPath = join(KEYS_DIR, 'public.pem');
+  return readFileSync(pubPath, 'utf8');
+}
+
+/**
+ * Generate a new attestation for search results.
+ */
+export function createAttestation(query, memories, agentId = null, sessionId = null) {
+  initializeKeys();
+
+  const attestationId = crypto.randomUUID();
+  const timestamp = new Date().toISOString();
+
+  // Map memories to {id, content_hash, score}
+  const memoriesRetrieved = memories.map(m => {
+    const contentHash = crypto.createHash('sha256').update(m.content).digest('hex');
+    return {
+      id: m.id,
+      content_hash: contentHash,
+      score: parseFloat(m.hybrid_score || 0)
+    };
+  });
+
+  // Fetch previous attestation hash for the hash chain
+  const lastAtt = getLastAttestation();
+  const previousHash = lastAtt ? lastAtt.hash : null;
+
+  // Construct document to sign (ordered keys to ensure canonical serialization)
+  const doc = {
+    attestation_id: attestationId,
+    query,
+    timestamp,
+    memories_retrieved: memoriesRetrieved,
+    agent_id: agentId || null,
+    session_id: sessionId || null,
+    previous_hash: previousHash
+  };
+
+  const dataToSign = JSON.stringify(doc);
+
+  // Sign document using Ed25519
+  const privateKey = getPrivateKey();
+  const signature = crypto.sign(null, Buffer.from(dataToSign), {
+    key: privateKey,
+    type: 'pkcs8',
+    format: 'pem'
+  }).toString('hex');
+
+  // Construct full record and compute its hash
+  const fullAttestation = {
+    ...doc,
+    signature
+  };
+
+  const hash = crypto.createHash('sha256').update(JSON.stringify(fullAttestation)).digest('hex');
+
+  const record = {
+    ...fullAttestation,
+    hash
+  };
+
+  // Persist to DB
+  insertAttestation(record);
+
+  return record;
+}
+
+/**
+ * Verify a single attestation record's signature and hash.
+ */
+export function verifyAttestationRecord(attestation) {
+  try {
+    const doc = {
+      attestation_id: attestation.attestation_id,
+      query: attestation.query,
+      timestamp: attestation.timestamp,
+      memories_retrieved: typeof attestation.memories_retrieved === 'string'
+        ? JSON.parse(attestation.memories_retrieved)
+        : attestation.memories_retrieved,
+      agent_id: attestation.agent_id || null,
+      session_id: attestation.session_id || null,
+      previous_hash: attestation.previous_hash || null
+    };
+
+    const dataToSign = JSON.stringify(doc);
+    const publicKey = getPublicKey();
+
+    // Verify signature
+    const isSignatureValid = crypto.verify(
+      null,
+      Buffer.from(dataToSign),
+      {
+        key: publicKey,
+        type: 'spki',
+        format: 'pem'
+      },
+      Buffer.from(attestation.signature, 'hex')
+    );
+
+    if (!isSignatureValid) {
+      return { valid: false, error: 'Signature verification failed' };
+    }
+
+    // Verify hash integrity
+    const fullRecord = {
+      ...doc,
+      signature: attestation.signature
+    };
+    const computedHash = crypto.createHash('sha256').update(JSON.stringify(fullRecord)).digest('hex');
+
+    if (computedHash !== attestation.hash) {
+      return { valid: false, error: 'Attestation hash mismatch' };
+    }
+
+    return { valid: true };
+  } catch (err) {
+    return { valid: false, error: err.message };
+  }
+}
+
+/**
+ * Verifies signature and chain integrity.
+ */
+export function verifyChainIntegrity(attestationId) {
+  const att = getAttestationById(attestationId);
+  if (!att) {
+    return { valid: false, error: `Attestation not found: ${attestationId}` };
+  }
+
+  const selfVerify = verifyAttestationRecord(att);
+  if (!selfVerify.valid) {
+    return selfVerify;
+  }
+
+  // If there's a previous link, check it
+  if (att.previous_hash) {
+    const prevAtt = getAttestationByHash(att.previous_hash);
+    if (!prevAtt) {
+      return { valid: false, error: `Broken chain: Previous attestation with hash ${att.previous_hash} not found` };
+    }
+
+    if (prevAtt.id >= att.id) {
+      return { valid: false, error: `Broken chain: Invalid sequence order` };
+    }
+
+    const prevVerify = verifyAttestationRecord(prevAtt);
+    if (!prevVerify.valid) {
+      return { valid: false, error: `Broken chain: Previous link is invalid: ${prevVerify.error}` };
+    }
+  }
+
+  return { valid: true, attestation: att };
+}
+
+/**
+ * Helper to fetch attestation by hash since it's not exposed globally.
+ */
+function getAttestationByHash(hash) {
+  return db.prepare('SELECT * FROM attestations WHERE hash = ?').get(hash) || null;
+}

package/src/cache.js

@@ -0,0 +1,122 @@
+/**
+ * cache.js — LRU Query Result Cache
+ * 
+ * In-memory LRU cache for search results to avoid
+ * re-computing embeddings for repeated queries.
+ * 
+ * - Configurable max size (default: 100 entries)
+ * - Configurable TTL (default: 5 minutes)
+ * - Automatic eviction of oldest entries when full
+ * - Full invalidation on write operations
+ */
+
+/**
+ * Simple LRU (Least Recently Used) cache with TTL support.
+ */
+export class LRUCache {
+  /**
+   * @param {number} maxSize - Maximum number of entries (default: 100)
+   * @param {number} ttlMs - Time-to-live in milliseconds (default: 300000 = 5 min)
+   */
+  constructor(maxSize = 100, ttlMs = 300000) {
+    this.maxSize = maxSize;
+    this.ttlMs = ttlMs;
+    this.cache = new Map();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Generate a cache key from query parameters.
+   * @param {string} query - The search query
+   * @param {number} limit - The result limit
+   * @returns {string} Cache key
+   */
+  static key(query, limit) {
+    return `${query}::${limit}`;
+  }
+
+  /**
+   * Get a cached value if it exists and hasn't expired.
+   * Moves the entry to the "most recently used" position.
+   * 
+   * @param {string} key - Cache key
+   * @returns {*|null} Cached value or null if miss/expired
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    // Check TTL expiry
+    if (Date.now() - entry.timestamp > this.ttlMs) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    // Move to end (most recently used) by re-inserting
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+
+  /**
+   * Store a value in the cache. Evicts oldest entry if at capacity.
+   * 
+   * @param {string} key - Cache key
+   * @param {*} value - Value to cache
+   */
+  set(key, value) {
+    // If key already exists, delete it first (to update position)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Evict oldest (first) entry if at capacity
+    if (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      this.cache.delete(oldestKey);
+    }
+
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Invalidate the entire cache. Called on write operations
+   * (add_memory, update_memory, delete_memory) to ensure
+   * search results are always fresh.
+   */
+  invalidate() {
+    const size = this.cache.size;
+    this.cache.clear();
+    if (size > 0) {
+      console.error(`[persyst-cache] Invalidated ${size} cached entries`);
+    }
+  }
+
+  /**
+   * Get cache statistics for monitoring.
+   * @returns {{ size: number, maxSize: number, ttlMs: number, hits: number, misses: number, hitRate: string }}
+   */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      ttlMs: this.ttlMs,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? `${((this.hits / total) * 100).toFixed(1)}%` : '0%'
+    };
+  }
+}
+
+// Singleton instance for search results
+export const searchCache = new LRUCache(100, 300000);