Persyst Mcp

Local-first, compliance-grade MCP memory layer for regulated enterprise coding teams using AI assistants.

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 — operating 100% offline with zero cloud egress.

---

Compliance-Grade Security Features

Persyst is built from the ground up for highly regulated enterprise environments (finance, healthcare, defense) subject to SOC 2, HIPAA, and the EU AI Act:

• 100% Data Residency (Zero-Egress): All vector calculations, full-text searches, and model inferences run locally on the developer's workstation. No database records or context data ever leave the local machine. Bypasses Business Associate Agreement (BAA) complexity for HIPAA.
• Cryptographic Chain of Custody: Every context retrieval generates an Ed25519 cryptographic signature sealing the query and retrieved memory hashes. Each attestation is chained to the previous one via SHA-256 hash chains, creating a tamper-evident audit ledger verifiable by security teams.
• Automatic Secret Redaction: Scans incoming log files and text writes to redact high-entropy secrets (API keys, JWTs, database strings, private keys) before they reach the persistent database.
• Event-Driven File Watching: Integrates chokidar for instant scanning of agent transcript folders, guaranteeing that your memories are synchronized immediately after each agent interaction.
• Workspace Project Isolation: Supports PERSYST_PROJECT environment partitioning, preventing cross-project context leaks while allowing shared enterprise compliance rules.

Read more in our compliance mapping guides:

• SOC 2 Type II Controls
• HIPAA Mapping & PHI Boundaries
• EU AI Act Article 13 Transparency
• Compliance Audit Trail Sample

---

Quick Start & Automatic IDE Setup

You don't need to configure MCP files manually. Persyst includes an automated setup CLI that detects installed editors and configures rule wrappers and global settings in seconds.

Automatic One-Command Setup

Run the setup wizard in your target project directory:

npx persyst-mcp init

This command automatically:

1. Generates local cryptographic Ed25519 keypairs in ~/.persyst.
2. Creates workspace rule files (.cursorrules, .windsurfrules, .clinerules, .persystrules.md) to instruct agents on memory retrieval.
3. Automatically writes global MCP server configurations for Cursor, Claude Code, Aider, and Continue.dev with project-scoped environment parameters (PERSYST_PROJECT).

---

Manual MCP Configuration

If you prefer to configure your agent manually, add the MCP server definition to your editor:

Claude Code (~/.claude.json) & Claude Desktop

{
  "mcpServers": {
    "persyst": {
      "command": "npx",
      "args": ["-y", "persyst-mcp"],
      "env": {
        "PERSYST_PROJECT": "my-project"
      }
    }
  }
}

VS Code (Cline / Roo Code)

Add to your user settings under cline_mcp_settings.json:

{
  "mcpServers": {
    "persyst": {
      "command": "npx",
      "args": ["-y", "persyst-mcp"],
      "env": {
        "PERSYST_PROJECT": "my-project"
      }
    }
  }
}

Cursor

Under Settings → Features → MCP:

1. Click + Add New MCP Server
2. Name: persyst
3. Type: stdio
4. Command: npx -y persyst-mcp

Aider

Append to your .aider.conf.yml project file:

mcp-server:
  - name: persyst
    command: npx -y persyst-mcp
    env:
      PERSYST_PROJECT: my-project

---

Passive Recording vs. Active Retrieval

Note on Agent Integration: Persyst operates in two complementary modes:

1. Passive Recording: The file watcher automatically extracts and saves memories from your agent conversation transcripts in the background.
2. Active Retrieval: The AI agent calls search_memories or get_optimized_context to fetch relevant context.

The IDE itself does not automatically inject retrieved memories into prompt inputs unless configured to do so via workspace rules (e.g. .cursorrules, .windsurfrules, .clinerules) or custom system prompt builders.

---

Available Tools (19 MCP Endpoints)

Tool	Description	Key Parameters
add_memory	Store a new memory with secret redaction & contradiction check	content, importance (0-1), agent_id, shared
search_memories	Hybrid keyword + semantic search with attestation	query, limit, agent_id
get_memory	Retrieve a specific memory by ID (boosts importance)	id, agent_id
update_memory	Update content & archive previous version	id, content, agent_id
delete_memory	Permanently delete a memory & clean knowledge graph edges	id
get_recent_memories	Fetch latest memories ordered by creation date	limit, agent_id
get_important_memories	Fetch memories ranked by importance score	limit, agent_id
get_optimized_context	Graph-hopped context prompt compiled within token budget	query, max_tokens, agent_id, intent
ingest_git_commits	Parse & import recent git commits as structured memories	repo_path, count
watch_git_repo	Poll repository for changes and auto-ingest new commits	repo_path
consolidate_memories	Semantic deduplication sweep merging similar memories	—
get_memory_history	Retrieve complete version history and semantic diffs	query
get_agent_stats	View agent reputation scores & contradiction metrics	—
export_audit_log	Export cryptographic attestation audit log (JSON/Markdown)	start_date, end_date
verify_attestation	Verify Ed25519 signature & SHA-256 chain integrity	attestation_id
add_entity	Add named entity to knowledge graph	name, type
link_entity_memory	Create edge between knowledge graph entity and memory	entity_id, memory_id, relation
search_by_entity	Query linked memories via knowledge graph traversal	entity_name

---

Local HTTP Gateway & Swarm Integration

In addition to STDIO transport, Persyst automatically launches a high-throughput local HTTP Gateway on port 4321 (http://127.0.0.1:4321).

• /health: Health check and database status
• /stats: Global memory & agent reputation statistics
• /system-prompt: Formatted prompt context injection
• /compliance/export: Cryptographic compliance audit report export (supports format=markdown)
• /events: Real-time Server-Sent Events (SSE) stream for agent swarms

---

How Hybrid Search Works

Persyst combines two complementary search strategies:

1. Keyword Search (SQLite FTS5) — Fast, exact string matching using BM25 ranking.
2. Semantic Search (sqlite-vec) — Deep meaning-based matching using local all-MiniLM-L6-v2 embeddings.

Results are merged dynamically. Keyword matches receive a score boost so exact matches rank at the top, while semantic similarity surfaces conceptually relevant memories even when different phrasing is used.

---

Tech Stack

• Runtime: Node.js 18+
• Database: SQLite via better-sqlite3 (synchronous, WAL mode)
• Vector Search: sqlite-vec (in-process, zero cloud egress)
• Full-Text Search: SQLite FTS5
• Embeddings: @huggingface/transformers + all-MiniLM-L6-v2 (384-dim, local ONNX)
• Watcher: chokidar event-driven file monitoring
• Protocol: MCP over stdio + HTTP Gateway

---

Backup & Migration

Persyst includes built-in JSONL export/import commands for portable memory backup and cross-machine migration:

# Export all memories to a JSONL file
npx persyst-mcp export

# Export to a specific file
npx persyst-mcp export my-backup.jsonl

# Preview import (dry run)
npx persyst-mcp import my-backup.jsonl --dry-run

# Import memories (deduplicates automatically)
npx persyst-mcp import my-backup.jsonl

---

License

MIT License. See LICENSE for details.