persyst-mcp 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# Persyst
+
+**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.
+
+## How It Works
+
+```
+Your AI Agent ←→ MCP (stdio) ←→ Persyst ←→ SQLite (local)
+```
+
+1. **Agent stores a memory** → Persyst saves it + generates a search embedding
+2. **Agent searches memories** → Persyst finds matches by both keywords AND meaning
+3. **"dark mode" ↔ "night theme"** → Semantic search understands synonyms
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g persyst-mcp
+```
+
+### 2. Add to Claude Code
+
+Edit your Claude Code MCP config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "persyst": {
+      "command": "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
+
+## Setup for Other Agents
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "persyst": {
+    "command": "persyst-mcp"
+  }
+}
+```
+
+### Aider
+
+```bash
+# Start the MCP server alongside Aider
+persyst-mcp &
+```
+
+## Available Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `add_memory` | Store a new memory | `content` (string), `importance` (0-1, optional) |
+| `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) |
+| `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:
+
+1. **Keyword Search (FTS5)** — Exact word matches using BM25 ranking
+2. **Semantic Search (sqlite-vec)** — Meaning-based using local embeddings
+
+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
+
+- **Runtime:** Node.js 18+
+- **Database:** SQLite via better-sqlite3
+- **Vector Search:** sqlite-vec (local, no cloud)
+- **Full-Text Search:** SQLite FTS5
+- **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
+
+# Run smoke test
+npm test
+
+# Start server directly
+node index.js
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+/**
+ * Persyst MCP Server — Entry Point
+ * 
+ * A local-first memory server for coding agents.
+ * Starts the MCP server on stdio transport.
+ * 
+ * Usage:
+ *   node index.js          (direct)
+ *   npx persyst-mcp        (via npm)
+ *   persyst-mcp            (if installed globally)
+ */
+
+import { startServer } from './src/server.js';
+
+startServer();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "persyst-mcp",
+  "version": "1.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"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test/smoke.js",
+    "test:heavy": "cross-env NODE_ENV=test node --test test/test_*.js"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "sqlite",
+    "local-first",
+    "ai",
+    "agents",
+    "semantic-search",
+    "knowledge-graph"
+  ],
+  "author": "Zayn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZayniBaloch/Peryst.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ZayniBaloch/Peryst/issues"
+  },
+  "homepage": "https://github.com/ZayniBaloch/Peryst#readme",
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "sqlite-vec": "^0.1.9",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "cross-env": "^10.1.0"
+  }
+}

package/src/database.js

@@ -0,0 +1,473 @@
+/**
+ * database.js — SQLite Database Setup & CRUD Operations
+ * 
+ * This file handles everything database-related:
+ * - Opens SQLite connection at ~/.persyst/persyst.db
+ * - Loads the sqlite-vec extension for vector search
+ * - Creates all tables (memories, FTS5 index, vector index)
+ * - Exports simple CRUD functions for other modules to use
+ * 
+ * IMPORTANT: better-sqlite3 is SYNCHRONOUS. No async/await here.
+ */
+
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+import { join } from 'path';
+import { homedir } from 'os';
+import { mkdirSync } from 'fs';
+
+// ============================================================
+// DATABASE LOCATION
+// Store in ~/.persyst/ so data persists across sessions
+// ============================================================
+
+const DB_DIR = join(homedir(), '.persyst');
+mkdirSync(DB_DIR, { recursive: true });
+const DB_PATH = process.env.NODE_ENV === 'test' ? ':memory:' : join(DB_DIR, 'persyst.db');
+
+// ============================================================
+// INITIALIZE CONNECTION
+// ============================================================
+
+const db = new Database(DB_PATH);
+db.pragma('journal_mode = WAL');   // Better performance for concurrent reads
+db.pragma('foreign_keys = ON');    // Enforce referential integrity
+
+// Load sqlite-vec BEFORE creating any vec0 tables
+sqliteVec.load(db);
+
+console.error(`[persyst] Database: ${DB_PATH}`);
+
+// ============================================================
+// CREATE TABLES
+// ============================================================
+
+// --- Main memories table ---
+db.exec(`
+  CREATE TABLE IF NOT EXISTS memories (
+    id              INTEGER PRIMARY KEY,
+    content         TEXT    NOT NULL,
+    importance_score REAL   DEFAULT 1.0,
+    created_at      INTEGER DEFAULT (unixepoch()),
+    last_accessed   INTEGER DEFAULT (unixepoch()),
+    access_count    INTEGER DEFAULT 0
+  )
+`);
+
+// --- FTS5 full-text search index (keyword search with BM25) ---
+db.exec(`
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    content,
+    content='memories',
+    content_rowid='id'
+  )
+`);
+
+// --- FTS5 auto-sync triggers ---
+// These keep the FTS index in sync when memories are added/updated/deleted.
+// Using try/catch because "CREATE TRIGGER IF NOT EXISTS" isn't supported.
+
+try {
+  db.exec(`
+    CREATE TRIGGER memories_fts_insert AFTER INSERT ON memories
+    BEGIN
+      INSERT INTO memories_fts(rowid, content) VALUES (new.id, new.content);
+    END
+  `);
+} catch (e) { /* trigger already exists */ }
+
+try {
+  db.exec(`
+    CREATE TRIGGER memories_fts_delete AFTER DELETE ON memories
+    BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content)
+      VALUES ('delete', old.id, old.content);
+    END
+  `);
+} catch (e) { /* trigger already exists */ }
+
+try {
+  db.exec(`
+    CREATE TRIGGER memories_fts_update AFTER UPDATE OF content ON memories
+    BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content)
+      VALUES ('delete', old.id, old.content);
+      INSERT INTO memories_fts(rowid, content)
+      VALUES (new.id, new.content);
+    END
+  `);
+} catch (e) { /* trigger already exists */ }
+
+// --- Vector table for semantic search (384-dim embeddings) ---
+db.exec(`
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_vec USING vec0(
+    embedding float[384]
+  )
+`);
+
+// --- Knowledge Graph: entities + edges ---
+// Entities are the "nouns" — people, files, tech, concepts
+db.exec(`
+  CREATE TABLE IF NOT EXISTS entities (
+    id         INTEGER PRIMARY KEY,
+    name       TEXT NOT NULL UNIQUE,
+    type       TEXT NOT NULL,
+    created_at INTEGER DEFAULT (unixepoch())
+  )
+`);
+
+// Edges connect entities to memories (or entities to entities)
+db.exec(`
+  CREATE TABLE IF NOT EXISTS edges (
+    id          INTEGER PRIMARY KEY,
+    source_id   INTEGER NOT NULL,
+    target_id   INTEGER NOT NULL,
+    relation    TEXT NOT NULL,
+    source_type TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    created_at  INTEGER DEFAULT (unixepoch())
+  )
+`);
+
+console.error('[persyst] Schema initialized ✓');
+
+// ============================================================
+// PREPARED STATEMENTS
+// Pre-compile SQL for performance. better-sqlite3 is synchronous.
+// ============================================================
+
+const stmts = {
+  // -- Insert --
+  insertMemory: db.prepare(
+    'INSERT INTO memories (content, importance_score) VALUES (?, ?)'
+  ),
+  insertVec: db.prepare(
+    'INSERT INTO memories_vec (rowid, embedding) VALUES (?, ?)'
+  ),
+
+  // -- Read --
+  getById: db.prepare(
+    'SELECT * FROM memories WHERE id = ?'
+  ),
+  getRecent: db.prepare(
+    'SELECT * FROM memories ORDER BY created_at DESC LIMIT ?'
+  ),
+  getImportant: db.prepare(
+    'SELECT * FROM memories ORDER BY importance_score DESC LIMIT ?'
+  ),
+
+  // -- Update --
+  updateContent: db.prepare(
+    'UPDATE memories SET content = ? WHERE id = ?'
+  ),
+
+  // -- Delete --
+  deleteMemory: db.prepare(
+    'DELETE FROM memories WHERE id = ?'
+  ),
+  deleteVec: db.prepare(
+    'DELETE FROM memories_vec WHERE rowid = ?'
+  ),
+
+  // -- Memory Lifecycle --
+  boost: db.prepare(`
+    UPDATE memories
+    SET access_count    = access_count + 1,
+        importance_score = MIN(importance_score + 0.1, 2.0),
+        last_accessed   = unixepoch()
+    WHERE id = ?
+  `),
+  decay: db.prepare(`
+    UPDATE memories
+    SET importance_score = importance_score * 0.95
+    WHERE (? - last_accessed) > 604800
+  `),
+
+  // -- Search --
+  searchFts: db.prepare(`
+    SELECT rowid AS id, rank
+    FROM memories_fts
+    WHERE memories_fts MATCH ?
+    ORDER BY rank
+    LIMIT ?
+  `),
+  searchVec: db.prepare(`
+    SELECT rowid, distance
+    FROM memories_vec
+    WHERE embedding MATCH ?
+    AND k = ?
+  `),
+
+  // -- Entity CRUD --
+  insertEntity: db.prepare(
+    'INSERT OR IGNORE INTO entities (name, type) VALUES (?, ?)'
+  ),
+  getEntityByName: db.prepare(
+    'SELECT * FROM entities WHERE name = ?'
+  ),
+  getEntityById: db.prepare(
+    'SELECT * FROM entities WHERE id = ?'
+  ),
+  getAllEntities: db.prepare(
+    'SELECT * FROM entities ORDER BY created_at DESC LIMIT ?'
+  ),
+  deleteEntity: db.prepare(
+    'DELETE FROM entities WHERE id = ?'
+  ),
+
+  // -- Edges --
+  insertEdge: db.prepare(
+    'INSERT INTO edges (source_id, target_id, relation, source_type, target_type) VALUES (?, ?, ?, ?, ?)'
+  ),
+  getEdgesBySource: db.prepare(
+    'SELECT * FROM edges WHERE source_id = ? AND source_type = ?'
+  ),
+  getEdgesByTarget: db.prepare(
+    'SELECT * FROM edges WHERE target_id = ? AND target_type = ?'
+  ),
+  deleteEdgesByMemory: db.prepare(
+    `DELETE FROM edges WHERE
+     (source_id = ? AND source_type = 'memory') OR
+     (target_id = ? AND target_type = 'memory')`
+  ),
+
+  // -- Dedup --
+  findMemoryByContent: db.prepare(
+    'SELECT id FROM memories WHERE content LIKE ? LIMIT 1'
+  )
+};
+
+// ============================================================
+// CRUD FUNCTIONS
+// Simple, one-purpose functions. No magic.
+// ============================================================
+
+/**
+ * Insert a new memory into the memories table.
+ * FTS5 index is auto-updated via trigger.
+ * @returns {number} The new memory's ID
+ */
+export function insertMemory(content, importance = 1.0) {
+  const result = stmts.insertMemory.run(content, importance);
+  return Number(result.lastInsertRowid);
+}
+
+/**
+ * Store an embedding vector for a memory.
+ * @param {number} id - Memory ID (used as rowid in vec table)
+ * @param {Float32Array} embedding - 384-dim embedding vector
+ */
+export function insertVector(id, embedding) {
+  // better-sqlite3 needs Buffer, sqlite-vec needs BigInt for rowid
+  stmts.insertVec.run(BigInt(id), Buffer.from(embedding.buffer));
+}
+
+/**
+ * Get a memory by ID. Boosts its importance on access.
+ * @returns {object|null} The memory row, or null if not found
+ */
+export function getMemory(id) {
+  const memory = stmts.getById.get(id);
+  if (memory) boostMemory(id);
+  return memory || null;
+}
+
+/**
+ * Get a memory by ID WITHOUT boosting. Used internally for search results.
+ * @returns {object|null} The memory row, or null if not found
+ */
+export function getMemoryById(id) {
+  return stmts.getById.get(id) || null;
+}
+
+/**
+ * Update a memory's content. FTS5 index auto-updates via trigger.
+ * Caller must also update the vector embedding separately.
+ * @returns {boolean} true if the memory existed and was updated
+ */
+export function updateMemoryContent(id, content) {
+  const result = stmts.updateContent.run(content, id);
+  return result.changes > 0;
+}
+
+/**
+ * Delete a vector embedding by memory ID.
+ */
+export function deleteVec(id) {
+  try { stmts.deleteVec.run(BigInt(id)); } catch (e) { /* may not exist */ }
+}
+
+/**
+ * Delete a memory and its vector embedding.
+ * FTS5 index auto-updates via trigger.
+ * @returns {boolean} true if the memory existed and was deleted
+ */
+export function deleteMemory(id) {
+  deleteVec(id);  // Remove vector first (no cascades on virtual tables)
+  const result = stmts.deleteMemory.run(id);
+  return result.changes > 0;
+}
+
+/**
+ * Get the N most recently created memories.
+ */
+export function getRecentMemories(limit = 10) {
+  return stmts.getRecent.all(limit);
+}
+
+/**
+ * Get the N most important memories (by importance_score).
+ */
+export function getImportantMemories(limit = 10) {
+  return stmts.getImportant.all(limit);
+}
+
+// ============================================================
+// MEMORY LIFECYCLE
+// ============================================================
+
+/**
+ * Boost a memory's importance when it's accessed.
+ * Increments access_count, adds 0.1 to importance (max 2.0),
+ * and updates last_accessed timestamp.
+ */
+export function boostMemory(id) {
+  stmts.boost.run(id);
+}
+
+/**
+ * Apply temporal decay to old memories.
+ * Reduces importance by 5% for memories not accessed in 7+ days.
+ * Called automatically every hour by the server.
+ */
+export function applyTemporalDecay() {
+  const now = Math.floor(Date.now() / 1000);
+  const result = stmts.decay.run(now);
+  if (result.changes > 0) {
+    console.error(`[persyst] Decay applied to ${result.changes} memories`);
+  }
+}
+
+// ============================================================
+// SEARCH HELPERS (used by search.js)
+// ============================================================
+
+/**
+ * Keyword search using FTS5 with BM25 ranking.
+ * @returns {Array<{id: number, rank: number}>}
+ */
+export function searchKeyword(query, limit = 10) {
+  try {
+    return stmts.searchFts.all(query, limit);
+  } catch (e) {
+    // FTS5 can throw on special characters in query
+    return [];
+  }
+}
+
+/**
+ * Vector similarity search using sqlite-vec KNN.
+ * @param {Float32Array} embedding - Query vector (384-dim)
+ * @returns {Array<{rowid: number, distance: number}>}
+ */
+export function searchVector(embedding, limit = 10) {
+  return stmts.searchVec.all(Buffer.from(embedding.buffer), limit);
+}
+
+// ============================================================
+// ENTITY FUNCTIONS (Knowledge Graph)
+// ============================================================
+
+/**
+ * Create a named entity (person, tech, file, concept, etc.).
+ * Silently skips if entity with that name already exists.
+ * @returns {number|null} The entity ID, or null if already existed
+ */
+export function insertEntity(name, type) {
+  const result = stmts.insertEntity.run(name, type);
+  if (result.changes === 0) {
+    // Already exists — return existing ID
+    const existing = stmts.getEntityByName.get(name);
+    return existing ? existing.id : null;
+  }
+  return Number(result.lastInsertRowid);
+}
+
+/**
+ * Get an entity by its name.
+ */
+export function getEntityByName(name) {
+  return stmts.getEntityByName.get(name) || null;
+}
+
+/**
+ * Get an entity by its ID.
+ */
+export function getEntityById(id) {
+  return stmts.getEntityById.get(id) || null;
+}
+
+/**
+ * Get all entities, most recent first.
+ */
+export function getAllEntities(limit = 50) {
+  return stmts.getAllEntities.all(limit);
+}
+
+/**
+ * Delete an entity and its edges.
+ */
+export function deleteEntity(id) {
+  stmts.deleteEntity.run(id);
+}
+
+/**
+ * Create an edge connecting two nodes (entity↔entity or entity↔memory).
+ */
+export function insertEdge(sourceId, targetId, relation, sourceType, targetType) {
+  stmts.insertEdge.run(sourceId, targetId, relation, sourceType, targetType);
+}
+
+/**
+ * Get all memories linked to an entity.
+ */
+export function getMemoriesByEntity(entityId) {
+  // Find edges where this entity is the source pointing to memories
+  const edges = stmts.getEdgesBySource.all(entityId, 'entity');
+  const memoryEdges = edges.filter(e => e.target_type === 'memory');
+  return memoryEdges.map(e => stmts.getById.get(e.target_id)).filter(Boolean);
+}
+
+/**
+ * Check if a memory with similar content already exists.
+ * Used for deduplication during git ingestion.
+ * @param {string} pattern - SQL LIKE pattern to match
+ * @returns {boolean}
+ */
+export function memoryExists(pattern) {
+  return stmts.findMemoryByContent.get(pattern) !== undefined;
+}
+
+/**
+ * Delete a memory and clean up its edges.
+ */
+export function deleteMemoryFull(id) {
+  stmts.deleteEdgesByMemory.run(id, id);
+  deleteVec(id);
+  const result = stmts.deleteMemory.run(id);
+  return result.changes > 0;
+}
+
+// ============================================================
+// CLEANUP
+// ============================================================
+
+/**
+ * Close the database connection. Call on shutdown.
+ */
+export function closeDatabase() {
+  db.close();
+  console.error('[persyst] Database closed');
+}
+
+export default db;

package/src/embeddings.js

@@ -0,0 +1,55 @@
+/**
+ * embeddings.js — Local Embedding Generation
+ * 
+ * Uses @huggingface/transformers with the all-MiniLM-L6-v2 model
+ * to generate 384-dimensional embeddings entirely on your machine.
+ * 
+ * - No API keys needed
+ * - No cloud calls
+ * - Model downloads once (~50MB), then cached locally
+ * - Returns Float32Array ready for sqlite-vec
+ */
+
+import './setup-wasm.js';
+import { env, pipeline } from '@huggingface/transformers';
+
+// Disable WASM caching to prevent blob: URL ESM dynamic import error in Node.js
+env.useWasmCache = false;
+
+// The embedding pipeline (lazy-loaded on first use)
+let extractor = null;
+
+/**
+ * Load the embedding model. Called automatically on first use.
+ * First run downloads the model (~50MB). Subsequent runs use cache.
+ */
+async function loadModel() {
+  if (extractor) return;
+
+  console.error('[persyst] Loading embedding model (first run downloads ~50MB)...');
+  extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+  console.error('[persyst] Embedding model loaded ✓');
+}
+
+/**
+ * Generate a 384-dimensional embedding for the given text.
+ * 
+ * @param {string} text - The text to embed
+ * @returns {Promise<Float32Array>} - Normalized 384-dim embedding vector
+ * 
+ * @example
+ *   const vec = await generateEmbedding("User prefers dark mode");
+ *   // vec is a Float32Array with 384 values
+ *   // Use vec.buffer to insert into sqlite-vec
+ */
+export async function generateEmbedding(text) {
+  await loadModel();
+
+  const output = await extractor(text, {
+    pooling: 'mean',     // Average all token embeddings into one vector
+    normalize: true      // Normalize to unit length (required for cosine similarity)
+  });
+
+  // output.data is already a flat Float32Array from the tensor
+  return new Float32Array(output.data);
+}

package/src/git.js

@@ -0,0 +1,97 @@
+/**
+ * git.js — Git Commit Ingestion
+ * 
+ * Reads git log from a repository and converts commits into memories.
+ * Useful for giving coding agents context about a project's history.
+ * 
+ * Each commit becomes a memory like:
+ *   "[abc1234] Fix login bug — by John on 2024-01-15"
+ * 
+ * Deduplicates by commit hash so you can ingest safely multiple times.
+ */
+
+import { execSync } from 'child_process';
+
+/**
+ * Read the N most recent git commits from a repository.
+ * 
+ * @param {string} repoPath - Absolute path to the git repo
+ * @param {number} count - Number of commits to read (default: 20)
+ * @returns {Array<{hash: string, message: string, author: string, date: string, fullText: string}>}
+ */
+export function getRecentCommits(repoPath, count = 20) {
+  try {
+    // Use a delimiter to split commits reliably
+    const DELIM = '---PERSYST-COMMIT---';
+    const format = `${DELIM}%n%H%n%an%n%ai%n%s%n%b`;
+
+    const output = execSync(
+      `git log -n ${count} --pretty=format:"${format}"`,
+      {
+        cwd: repoPath,
+        encoding: 'utf-8',
+        timeout: 10000,      // 10s timeout
+        stdio: ['pipe', 'pipe', 'pipe']  // Suppress stderr
+      }
+    );
+
+    // Parse the output into commit objects
+    const commits = [];
+    const blocks = output.split(DELIM).filter(b => b.trim());
+
+    for (const block of blocks) {
+      const lines = block.trim().split('\n');
+      if (lines.length < 4) continue;
+
+      const hash = lines[0].trim();
+      const author = lines[1].trim();
+      const date = lines[2].trim().split(' ')[0]; // Just the date part
+      const subject = lines[3].trim();
+      const body = lines.slice(4).join(' ').trim();
+
+      // Build a readable memory string
+      const fullText = body
+        ? `[${hash.slice(0, 7)}] ${subject} — by ${author} on ${date}. ${body}`
+        : `[${hash.slice(0, 7)}] ${subject} — by ${author} on ${date}`;
+
+      commits.push({ hash, message: subject, author, date, fullText });
+    }
+
+    return commits;
+  } catch (err) {
+    // Not a git repo, or git not installed
+    const message = err.message || String(err);
+    if (message.includes('not a git repository')) {
+      throw new Error(`Not a git repository: ${repoPath}`);
+    }
+    if (message.includes('ENOENT') || message.includes('not recognized')) {
+      throw new Error('Git is not installed or not in PATH');
+    }
+    throw new Error(`Failed to read git log: ${message}`);
+  }
+}
+
+/**
+ * Get changed files from a specific commit.
+ * Useful for linking commits to file entities.
+ * 
+ * @param {string} repoPath - Absolute path to the git repo
+ * @param {string} hash - Full commit hash
+ * @returns {string[]} List of changed file paths
+ */
+export function getCommitFiles(repoPath, hash) {
+  try {
+    const output = execSync(
+      `git diff-tree --no-commit-id --name-only -r ${hash}`,
+      {
+        cwd: repoPath,
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }
+    );
+    return output.trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/search.js

@@ -0,0 +1,109 @@
+/**
+ * search.js — Hybrid Search Engine
+ * 
+ * Combines two search strategies for best results:
+ * 
+ *   1. KEYWORD SEARCH (FTS5 + BM25)
+ *      → Finds exact word matches. Fast. "React" finds "React".
+ * 
+ *   2. SEMANTIC SEARCH (sqlite-vec + embeddings)
+ *      → Finds by meaning. "dark mode" matches "night theme".
+ * 
+ *   3. HYBRID = keyword + semantic merged
+ *      → Keyword matches get a +0.2 score boost on top of semantic score.
+ *      → Best of both worlds.
+ */
+
+import { generateEmbedding } from './embeddings.js';
+import {
+  searchKeyword,
+  searchVector,
+  getMemoryById,
+  boostMemory
+} from './database.js';
+
+// ============================================================
+// HYBRID SEARCH (the main export)
+// ============================================================
+
+/**
+ * Search memories using both keyword and semantic strategies.
+ * 
+ * How it works:
+ *   1. Run FTS5 keyword search → get matching memory IDs
+ *   2. Run vector semantic search → get memories ranked by meaning
+ *   3. If a memory appears in BOTH, boost its score by +0.2
+ *   4. Sort by combined score, return top N
+ * 
+ * @param {string} queryText - What to search for
+ * @param {number} limit - Max results to return (default: 5)
+ * @returns {Promise<Array>} Ranked search results with scores
+ * 
+ * @example
+ *   const results = await searchHybrid("night theme", 5);
+ *   // Will find memories about "dark mode" via semantic match
+ */
+export async function searchHybrid(queryText, limit = 5) {
+  // --- Step 1: Keyword search (fast, exact matches) ---
+  const keywordHits = searchKeyword(queryText, limit * 2);
+  const keywordIds = new Set(keywordHits.map(r => r.id));
+
+  // --- Step 2: Semantic search (meaning-based) ---
+  const queryEmbedding = await generateEmbedding(queryText);
+  const vecHits = searchVector(queryEmbedding, limit * 2);
+
+  const semanticResults = vecHits.map(r => ({
+    id: r.rowid,
+    distance: r.distance,
+    // Convert L2 distance to 0-1 similarity score
+    // For normalized vectors: cosine_sim = 1 - (L2_distance² / 2)
+    similarity: Math.max(0, 1 - (r.distance * r.distance) / 2)
+  }));
+
+  // --- Step 3: Merge results with keyword boost ---
+  const combined = semanticResults.map(r => ({
+    id: r.id,
+    similarity: r.similarity,
+    hybrid_score: r.similarity + (keywordIds.has(r.id) ? 0.2 : 0),
+    keyword_match: keywordIds.has(r.id)
+  }));
+
+  // Add keyword-only hits that semantic search missed
+  const semanticIds = new Set(semanticResults.map(r => r.id));
+  for (const id of keywordIds) {
+    if (!semanticIds.has(id)) {
+      combined.push({
+        id,
+        similarity: 0,
+        hybrid_score: 0.2,  // Keyword-only base score
+        keyword_match: true
+      });
+    }
+  }
+
+  // --- Step 4: Sort by score, fetch full data, return top N ---
+  combined.sort((a, b) => b.hybrid_score - a.hybrid_score);
+  const topResults = combined.slice(0, limit);
+
+  const results = topResults
+    .map(r => {
+      const memory = getMemoryById(r.id);
+      if (!memory) return null;  // Memory was deleted between search and fetch
+
+      // Boost importance since this memory was useful
+      boostMemory(r.id);
+
+      return {
+        id: memory.id,
+        content: memory.content,
+        importance_score: memory.importance_score,
+        created_at: memory.created_at,
+        similarity: r.similarity.toFixed(4),
+        hybrid_score: r.hybrid_score.toFixed(4),
+        keyword_match: r.keyword_match
+      };
+    })
+    .filter(Boolean);  // Remove nulls from deleted memories
+
+  return results;
+}

package/src/server.js

@@ -0,0 +1,52 @@
+/**
+ * server.js — MCP Server Setup
+ * 
+ * Creates the MCP server, registers all tools, and connects
+ * via stdio transport (the standard MCP communication method).
+ * 
+ * IMPORTANT: Never write to stdout — it's reserved for MCP protocol.
+ * All logging goes to stderr via console.error().
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+import { applyTemporalDecay, closeDatabase } from './database.js';
+
+/**
+ * Start the Persyst MCP server.
+ * This is called from index.js (the entry point).
+ */
+export async function startServer() {
+  // --- Create MCP server ---
+  const server = new McpServer({
+    name: 'persyst',
+    version: '1.0.0'
+  });
+
+  // --- Register all 7 tools ---
+  registerTools(server);
+  console.error('[persyst] 7 tools registered ✓');
+
+  // --- Start temporal decay timer ---
+  // Runs every hour: reduces importance of memories not accessed in 7+ days
+  const decayTimer = setInterval(applyTemporalDecay, 3600000);
+
+  // --- Graceful shutdown ---
+  const shutdown = () => {
+    console.error('[persyst] Shutting down...');
+    clearInterval(decayTimer);
+    closeDatabase();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // --- Connect via stdio ---
+  // This is how Claude Code, Cursor, and Aider communicate with us
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('[persyst] MCP server running on stdio ✓');
+  console.error('[persyst] Ready to receive tool calls');
+}

package/src/setup-wasm.js

@@ -0,0 +1,70 @@
+import * as ONNX_NODE from 'onnxruntime-node';
+import * as ONNX_WEB from 'onnxruntime-web/webgpu';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const onnxWebPath = require.resolve('onnxruntime-web');
+const wasmDir = path.dirname(onnxWebPath);
+
+// Redirect native Node session creation to WebAssembly session creation
+ONNX_NODE.InferenceSession.create = ONNX_WEB.InferenceSession.create;
+
+// Override URL.createObjectURL to return file URL of the existing local file
+const originalCreateObjectURL = URL.createObjectURL;
+URL.createObjectURL = (blob) => {
+  const type = blob.type || '';
+  if (type.includes('javascript') || type.includes('mjs')) {
+    const filePath = path.join(wasmDir, 'ort-wasm-simd-threaded.asyncify.mjs');
+    const fileUrl = pathToFileURL(filePath).href;
+    return fileUrl;
+  }
+  return originalCreateObjectURL(blob);
+};
+
+// Override global fetch to load ONNX WASM binaries and model files from local disk
+const originalFetch = globalThis.fetch;
+globalThis.fetch = async (url, options) => {
+  const urlStr = typeof url === 'string' ? url : url.url;
+  
+  let isLocal = false;
+  let filePath = '';
+  
+  if (urlStr.startsWith('file://')) {
+    isLocal = true;
+    filePath = fileURLToPath(urlStr);
+  } else if (!urlStr.startsWith('http://') && !urlStr.startsWith('https://') && !urlStr.startsWith('data:')) {
+    isLocal = true;
+    filePath = urlStr;
+  }
+  
+  // Intercept onnxruntime-web CDN URLs and route them to node_modules/onnxruntime-web/dist
+  if (urlStr.includes('onnxruntime-web') || urlStr.includes('ort-wasm')) {
+    isLocal = true;
+    const filename = urlStr.split('/').pop().split('?')[0].split('#')[0];
+    filePath = path.join(wasmDir, filename);
+  }
+  
+  if (isLocal) {
+    filePath = path.normalize(filePath);
+    try {
+      const buffer = fs.readFileSync(filePath);
+      let contentType = 'application/octet-stream';
+      if (filePath.endsWith('.wasm')) contentType = 'application/wasm';
+      else if (filePath.endsWith('.mjs') || filePath.endsWith('.js')) contentType = 'text/javascript';
+      
+      return new Response(buffer, {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': contentType }
+      });
+    } catch (err) {
+      console.error('[persyst] Failed to read local file:', filePath, err.message);
+      throw err;
+    }
+  }
+  
+  return originalFetch(url, options);
+};

package/src/tools.js

@@ -0,0 +1,290 @@
+/**
+ * tools.js — MCP Tool Definitions & Handlers
+ * 
+ * Defines all 11 tools that AI agents can call via MCP:
+ * 
+ *   Core (MVP):
+ *   1. add_memory             — Store a new memory
+ *   2. search_memories        — Hybrid keyword + semantic search
+ *   3. get_memory             — Get one memory by ID
+ *   4. update_memory          — Update content (re-embeds automatically)
+ *   5. delete_memory          — Remove a memory permanently
+ *   6. get_recent_memories    — Latest N memories
+ *   7. get_important_memories — Top N by importance
+ * 
+ *   Advanced (Phase 3):
+ *   8. ingest_git_commits     — Import git history as memories
+ *   9. add_entity             — Create a named entity
+ *  10. link_entity_memory     — Connect entity ↔ memory
+ *  11. search_by_entity       — Find memories linked to an entity
+ * 
+ * Uses Zod schemas for input validation (required by McpServer).
+ */
+
+import { z } from 'zod';
+import { generateEmbedding } from './embeddings.js';
+import {
+  insertMemory,
+  insertVector,
+  getMemory,
+  updateMemoryContent,
+  deleteMemory,
+  deleteVec,
+  getRecentMemories,
+  getImportantMemories,
+  insertEntity,
+  getEntityByName,
+  insertEdge,
+  getMemoriesByEntity,
+  getAllEntities,
+  memoryExists
+} from './database.js';
+import { searchHybrid } from './search.js';
+import { getRecentCommits } from './git.js';
+
+/**
+ * Register all MCP tools on the server.
+ * @param {McpServer} server - The MCP server instance
+ */
+export function registerTools(server) {
+
+  // ========================================
+  // 1. ADD MEMORY
+  // ========================================
+  server.tool(
+    'add_memory',
+    'Store a new memory. It will be searchable by both keywords and meaning.',
+    {
+      content: z.string().describe('The memory content to store'),
+      importance: z.number().min(0).max(1).default(1.0)
+        .describe('Importance score from 0 (low) to 1 (high)')
+    },
+    async ({ content, importance }) => {
+      const id = insertMemory(content, importance);
+      const embedding = await generateEmbedding(content);
+      insertVector(id, embedding);
+
+      return text({ success: true, id, message: `Memory #${id} stored` });
+    }
+  );
+
+  // ========================================
+  // 2. SEARCH MEMORIES
+  // ========================================
+  server.tool(
+    'search_memories',
+    'Search memories using hybrid keyword + semantic search. Finds exact matches AND similar meanings (e.g. "dark mode" finds "night theme").',
+    {
+      query: z.string().describe('What to search for'),
+      limit: z.number().default(5).describe('Max results (default: 5)')
+    },
+    async ({ query, limit }) => {
+      const results = await searchHybrid(query, limit);
+      return text({ results, count: results.length });
+    }
+  );
+
+  // ========================================
+  // 3. GET MEMORY
+  // ========================================
+  server.tool(
+    'get_memory',
+    'Get a specific memory by its ID. Boosts its importance automatically.',
+    {
+      id: z.number().describe('Memory ID to retrieve')
+    },
+    async ({ id }) => {
+      const memory = getMemory(id);
+      if (!memory) return text({ error: `Memory #${id} not found` });
+      return text(memory);
+    }
+  );
+
+  // ========================================
+  // 4. UPDATE MEMORY
+  // ========================================
+  server.tool(
+    'update_memory',
+    'Update the content of an existing memory. Automatically re-generates the search embedding.',
+    {
+      id: z.number().describe('Memory ID to update'),
+      content: z.string().describe('New memory content')
+    },
+    async ({ id, content }) => {
+      const updated = updateMemoryContent(id, content);
+      if (!updated) return text({ error: `Memory #${id} not found` });
+
+      // Re-generate embedding for updated content
+      const embedding = await generateEmbedding(content);
+      deleteVec(id);
+      insertVector(id, embedding);
+
+      return text({ success: true, id, message: `Memory #${id} updated` });
+    }
+  );
+
+  // ========================================
+  // 5. DELETE MEMORY
+  // ========================================
+  server.tool(
+    'delete_memory',
+    'Permanently delete a memory by its ID.',
+    {
+      id: z.number().describe('Memory ID to delete')
+    },
+    async ({ id }) => {
+      const deleted = deleteMemory(id);
+      if (!deleted) return text({ error: `Memory #${id} not found` });
+      return text({ success: true, id, message: `Memory #${id} deleted` });
+    }
+  );
+
+  // ========================================
+  // 6. GET RECENT MEMORIES
+  // ========================================
+  server.tool(
+    'get_recent_memories',
+    'Get the most recently created memories, newest first.',
+    {
+      limit: z.number().default(10).describe('How many to return (default: 10)')
+    },
+    async ({ limit }) => {
+      const memories = getRecentMemories(limit);
+      return text({ memories, count: memories.length });
+    }
+  );
+
+  // ========================================
+  // 7. GET IMPORTANT MEMORIES
+  // ========================================
+  server.tool(
+    'get_important_memories',
+    'Get memories ranked by importance score, highest first.',
+    {
+      limit: z.number().default(10).describe('How many to return (default: 10)')
+    },
+    async ({ limit }) => {
+      const memories = getImportantMemories(limit);
+      return text({ memories, count: memories.length });
+    }
+  );
+
+  // ========================================
+  // 8. INGEST GIT COMMITS
+  // ========================================
+  server.tool(
+    'ingest_git_commits',
+    'Import recent git commits from a repository as memories. Each commit becomes a searchable memory. Deduplicates automatically — safe to call multiple times.',
+    {
+      repo_path: z.string().describe('Absolute path to the git repository'),
+      count: z.number().default(20).describe('Number of recent commits to import (default: 20)')
+    },
+    async ({ repo_path, count }) => {
+      try {
+        const commits = getRecentCommits(repo_path, count);
+        let added = 0;
+        let skipped = 0;
+
+        for (const commit of commits) {
+          // Dedup by commit hash prefix
+          const hashPrefix = commit.hash.slice(0, 7);
+          if (memoryExists(`[${hashPrefix}]%`)) {
+            skipped++;
+            continue;
+          }
+
+          // Store commit as memory
+          const id = insertMemory(commit.fullText, 0.6);
+          const embedding = await generateEmbedding(commit.fullText);
+          insertVector(id, embedding);
+
+          // Auto-create author entity and link
+          const authorId = insertEntity(commit.author, 'person');
+          if (authorId) {
+            insertEdge(authorId, id, 'authored', 'entity', 'memory');
+          }
+
+          added++;
+        }
+
+        return text({
+          success: true,
+          added,
+          skipped,
+          total_commits: commits.length,
+          message: `Ingested ${added} commits (${skipped} already existed)`
+        });
+      } catch (err) {
+        return text({ error: err.message });
+      }
+    }
+  );
+
+  // ========================================
+  // 9. ADD ENTITY
+  // ========================================
+  server.tool(
+    'add_entity',
+    'Create a named entity (person, tech, project, concept, file). Entities can be linked to memories for graph traversal.',
+    {
+      name: z.string().describe('Entity name (e.g. "React", "John", "auth-service")'),
+      type: z.string().describe('Entity type: person, tech, project, concept, file')
+    },
+    async ({ name, type }) => {
+      const id = insertEntity(name, type);
+      return text({ success: true, id, name, type, message: `Entity "${name}" created` });
+    }
+  );
+
+  // ========================================
+  // 10. LINK ENTITY TO MEMORY
+  // ========================================
+  server.tool(
+    'link_entity_memory',
+    'Connect an entity to a memory with a relationship label (e.g. "mentions", "is_about", "decided_by").',
+    {
+      entity_name: z.string().describe('Name of the entity'),
+      memory_id: z.number().describe('ID of the memory to link'),
+      relation: z.string().default('mentions').describe('Relationship type (e.g. mentions, is_about, decided_by)')
+    },
+    async ({ entity_name, memory_id, relation }) => {
+      const entity = getEntityByName(entity_name);
+      if (!entity) return text({ error: `Entity "${entity_name}" not found. Create it first with add_entity.` });
+
+      const memory = getMemory(memory_id);
+      if (!memory) return text({ error: `Memory #${memory_id} not found` });
+
+      insertEdge(entity.id, memory_id, relation, 'entity', 'memory');
+      return text({ success: true, entity: entity_name, memory_id, relation, message: `Linked "${entity_name}" → memory #${memory_id}` });
+    }
+  );
+
+  // ========================================
+  // 11. SEARCH BY ENTITY
+  // ========================================
+  server.tool(
+    'search_by_entity',
+    'Find all memories linked to a specific entity. Returns memories connected via edges in the knowledge graph.',
+    {
+      entity_name: z.string().describe('Name of the entity to search for')
+    },
+    async ({ entity_name }) => {
+      const entity = getEntityByName(entity_name);
+      if (!entity) return text({ error: `Entity "${entity_name}" not found` });
+
+      const memories = getMemoriesByEntity(entity.id);
+      return text({ entity, memories, count: memories.length });
+    }
+  );
+}
+
+// ============================================================
+// HELPER
+// ============================================================
+
+/** Format a response as MCP text content */
+function text(data) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+  };
+}