Skip to content

README.md

Latest commit

 

History

History
207 lines (157 loc) · 7.42 KB

README.md

File metadata and controls

207 lines (157 loc) · 7.42 KB

Synapsis

Synapsis

Persistent Memory Engine for AI Agents
Built with Rust. MCP-native. Zero-trust security.

Rust License GitHub

Synapsis is a persistent memory engine for AI agents. It implements the Model Context Protocol (MCP) to give LLM agents durable, searchable memory across sessions. Written in pure Rust with SQLite + FTS5 storage and optional post-quantum cryptography.

Quick Start

git clone https://github.com/methodwhite/synapsis.git
cd synapsis
cargo build --release

# MCP server (stdio) - for local AI agents
./target/release/synapsis-mcp

# Multi-agent MCP server (HTTP/SSE)
./target/release/synapsis

Prerequisites: Rust 1.75+ (install)

Installation

Linux / macOS

# Linux (x86_64 / ARM64)
curl -fsSL https://raw.githubusercontent.com/methodwhite/synapsis/main/scripts/install-linux.sh | bash

# macOS (Intel / Apple Silicon)
curl -fsSL https://raw.githubusercontent.com/methodwhite/synapsis/main/scripts/install-macos.sh | bash

Windows (PowerShell)

# Run as Administrator
iwr -Uri https://raw.githubusercontent.com/methodwhite/synapsis/main/scripts/install.ps1 -OutFile install.ps1
.\install.ps1

Build from Source (all platforms)

git clone https://github.com/methodwhite/synapsis.git
cd synapsis
cargo build --release

The build produces three binaries:

Binary Purpose
synapsis Multi-agent MCP server (HTTP/SSE)
synapsis-mcp Single-agent MCP server (stdio)
synapsis-server HTTP API server

Features

  • Persistent Memory — Save, search, and retrieve observations with full-text search (FTS5 + BM25 ranking)
  • MCP-native — Drop-in compatible with any MCP client (Claude Code, Cursor, Windsurf, OpenCode, Qwen)
  • Multi-agent — Shared database, distributed locking, task queues for concurrent agent workflows
  • Context Management — Tiered context with compression, isolation, and automatic budget tracking
  • Security — Optional SQLCipher encryption at rest, integrity hashing, TPM-backed MFA, PQC encryption
  • Watchdog — Filesystem integrity monitoring with event auditing and anomaly detection
  • Anti-Brick — Protection against destructive system commands
  • Recycle Bin — TTL-based categorization with search and undelete
  • Cross-platform — Linux, macOS, Windows (WSL2 or native MSVC)

Architecture

Synapsis Architecture

The system follows a hexagonal (ports & adapters) architecture with three layers:

  • Presentation — MCP stdio/HTTP, CLI, TUI interfaces
  • Core — Business logic (orchestrator, workers, task queue, auth, watchdog, recycle)
  • Infrastructure — SQLite + FTS5 storage, agent registry, context management, PQC vault

MCP Tools

Tool Description
mem_save Save an observation to persistent memory
mem_search Search persistent memory across all sessions
mem_context Get recent context from current or previous sessions
mem_timeline Get chronological timeline of observations
mem_stats Get memory statistics
mem_delete Delete an observation by ID (soft-delete)
memory_search [alias] Search Synapsis persistent memory
memory_add [alias] Add observation to Synapsis
memory_timeline [alias] Get memory timeline
memory_stats [alias] Get memory statistics
agent_register Register a new agent
agent_list List all registered agents
task_create Create a new task
task_list List all tasks
skill_register Register a new skill
skill_list List all registered skills
ghost_audit Trigger proactive audit of a file or path
pqc_encrypt Encrypt sensitive data using Post-Quantum Cryptography
wasm_run Run a sandboxed WASM skill
antibrick_scan Scan a command for potential brick threats
antibrick_enable Enable or disable anti-brick protection
antibrick_stats Get anti-brick protection stats
watchdog_stats Get filesystem watchdog stats
watchdog_verify Verify integrity of monitored files
watchdog_snapshot Create integrity snapshot of a path
watchdog_events Get recent watchdog events
watchdog_check_path Check if a path is protected by watchdog
browser_navigate Fetch a web page as an HTTP client
browser_snapshot Get a structured snapshot of a web page
mcp_call Call a tool on another MCP server via HTTP
db_backup Create a backup of the Synapsis database
db_integrity Run PRAGMA integrity_check on the database
db_prune Soft-delete observations older than N days
db_vacuum Reclaim unused space in the database

Storage

Synapsis uses SQLite with FTS5 full-text search for all persistent storage:

  • Observations — Title, content, project, type, scope, integrity hash
  • Sessions — Agent session lifecycle tracking with activity timelines
  • Task Queue — Multi-agent task coordination with priority and retry
  • Agent Registry — Agent skills, capacity, and discovery
  • Context Registry — Tiered context with hot/warm/cold states and compression
  • Locks — Distributed mutex for concurrent agent access

IDE Integration

Platform Setup
VS Code / Cursor / Windsurf Config from plugins/vscode/
Claude Code Plugin from plugins/claude-code/
JetBrains Plugin from plugins/jetbrains/
Gemini CLI Script from plugins/gemini-cli/

Environment Variables

Variable Description
SYNAPSIS_DB_KEY Hex-encoded encryption key (SQLCipher)
SYNAPSIS_DB_KEY_BASE64 Base64-encoded encryption key
SYNAPSIS_DATA_DIR Custom data directory (default: ~/.local/share/synapsis)
SYNAPSIS_QUIET Suppress informational output
SYNAPSIS_LOG Set log level (debug, info, warn, error)
SYNAPSIS_API_KEYS Comma-separated API keys for auth
SYNAPSIS_PORT HTTP server port (default: 7438)

Documentation

Document Description
Architecture System architecture diagram (draw.io)
Multi-Agent Multi-agent coordination and orchestration
Deployment Production deployment guide
YOLO Mode Autonomous operation mode
Roadmap Development roadmap

License

Business Source License 1.1 — see LICENSE for details.

Commercial use requires a separate license for entities with 3+ employees or over $100k annual revenue. Non-commercial, educational, and personal use is free. Changes to Apache 2.0 on March 23, 2030.

Built with Rust by MethodWhite