# SYNAPSE DOCUMENTATION — Complete Reference
# Generated: 2026-07-18T04:06:21.452Z
# Total articles: 47
This document contains the complete Synapse API documentation.
Base URL: https://synapse.schaefer.zone
Language: en
========================================================================
## CATEGORY: GETTING STARTED
Everything you need to get started with Synapse.
────────────────────────────────────────────────────────────
# Authentication & Mind Keys
SUMMARY: How Synapse authentication works: Mind Keys for agents, JWTs for humans, ?key= for URL-only tools.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Authentication & Mind Keys
Synapse uses two authentication methods, each optimized for a different use case.
Understanding the difference is essential for building reliable integrations.
Two Auth Methods
| Method | Use Case | Rate Limit | Expiry |
|--------|----------|------------|--------|
| Mind Key | LLM agents, automated tools | None (header) / 60 min (query) | Never |
| JWT | Human-facing UI, account ops | None | 7 days |
Mind Key (for Agents)
A Mind Key is a tenant-scoped API token. It authenticates a single mind's data
(memories, tasks, chat, scripts, etc.). Use it for:
- LLM agents calling the API
- Background automation scripts
- MCP server configuration
- Any long-lived integration
Header authentication (recommended)
[CODE BLOCK]
Query parameter (for URL-only tools)
[CODE BLOCK]
> [!WARNING]
> The query parameter is rate-limited to 60 requests per minute.
> The Bearer header has no rate limit. Use the header whenever your client
> supports custom headers.
Creating a Mind Key
[CODE BLOCK]
Response includes — save it immediately, it's shown only once.
Listing your minds
[CODE BLOCK]
Deleting a mind (irreversible!)
[CODE BLOCK]
JWT (for Humans)
JWTs authenticate the user account, not a specific mind. Use them for:
- Account registration and login
- Creating / listing / deleting minds
- Sharing minds with other users
- Web Push subscription management
Register
[CODE BLOCK]
Returns:
Login
[CODE BLOCK]
Returns:
JWT expiry
JWTs expire after 7 days. When a JWT expires, simply call again to
get a fresh one. The Mind Key never expires, so existing agent integrations
keep working.
Security Best Practices
> [!CRITICAL]
> - Never commit Mind Keys to git. Use environment variables.
> - Never log Mind Keys. Mask them in logs ().
> - Rotate keys if you suspect a leak (delete the mind, create a new one).
> - Use one mind per project to limit blast radius if a key leaks.
Environment variable pattern
[CODE BLOCK]
[CODE BLOCK]
MCP server config
[CODE BLOCK]
Multi-Mind Pattern
Each user can have multiple minds. Common patterns:
| Mind Name | Purpose |
|-----------|---------|
| | Job-related memories |
| | Personal preferences, family |
| | Specific project context |
| | Learning progress |
| | General-purpose fallback |
Use different Mind Keys for different LLM sessions to keep contexts isolated.
Rate Limits
| Auth Method | Limit | Scope |
|-------------|-------|-------|
| Mind Key (header) | None | Per-mind |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | None | Per-user |
| Public endpoints | None | Global |
Rate limit headers (, , )
are included in responses when applicable.
Next Steps
- Mind Key vs JWT — when to use which
- Memory API — what you can do with a Mind Key
- User API — account management with JWTs
────────────────────────────────────────────────────────────
# Mind Key vs JWT — What When?
SUMMARY: Decision guide: Mind Key for agent data access, JWT for account management.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — What When?
Synapse has two authentication tokens. Choosing the wrong one leads to 401 errors.
This guide gives you a clear decision framework.
Quick Decision Table
| You want to... | Use |
|----------------|-----|
| Store / recall memories | Mind Key |
| Send / poll chat messages | Mind Key |
| Manage tasks | Mind Key |
| Store scripts | Mind Key |
| Register webhooks | Mind Key |
| Control computers | Mind Key (user-side) / Computer Token (agent-side) |
| Register a user account | None (public) |
| Login | None (public) |
| Create / list / delete minds | JWT |
| Share a mind with another user | JWT |
| Subscribe to web push notifications | JWT |
| View audit log | Mind Key |
The Simple Rule
> [!TIP]
> If it touches a single mind's data → Mind Key.
> If it manages the account or mind metadata → JWT.
Mind Key — Data Access Token
A Mind Key grants access to one mind's data. It's a long-lived token that
never expires (until the mind is deleted). Perfect for:
- LLM agents persisting memories across sessions
- Background cron jobs
- MCP server configuration
- Webhook integrations
- Mobile apps reading memory
What Mind Key can do
- — read all memories in this mind
- — store/update memories
- — read chat messages
- — send chat messages
- — list tasks
- — create tasks
- — store scripts
- — register webhooks
- — queue computer commands
What Mind Key CANNOT do
- Create / list / delete minds (need JWT)
- Share mind with another user (need JWT)
- View user account info (need JWT)
- Subscribe to web push (need JWT)
JWT — Account Management Token
A JWT authenticates the user account. It expires after 7 days and is used
for account-level operations that span multiple minds or involve other users.
What JWT can do
- — create a new mind (returns a new Mind Key)
- — list all minds for this user
- — delete a mind
- — share a mind with another user
- — subscribe to web push notifications
- — list mind shares
What JWT CANNOT do
- Read / write memories (need Mind Key)
- Send chat messages (need Mind Key)
- Manage tasks (need Mind Key)
- Register webhooks (need Mind Key)
Special Case: Computer Token
The endpoints (agent-facing, for the screen-remote-agent)
use a third token type: the Computer Token. This token is returned by
when redeeming an install code, and is specific to
one registered computer.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key or JWT |
| | Mind Key or JWT |
Common Patterns
Pattern 1: Single LLM Agent
1. Register once → get JWT
2. Create one mind → get Mind Key
3. LLM uses Mind Key for everything
Pattern 2: Multi-Project Agent
1. Register once → get JWT
2. Create multiple minds (work, personal, project-x) → get multiple Mind Keys
3. LLM loads different Mind Key based on context
Pattern 3: Team Sharing
1. User A creates a mind → gets Mind Key A
2. User A shares with User B via JWT ()
3. User B can now access via their own JWT
4. For LLM access, User B needs to create their own Mind Key (or use A's)
Pattern 4: MCP Server
MCP servers always use Mind Key (set via env var). One MCP
server instance = one mind. For multi-mind access, run multiple MCP instances
or implement client-side mind switching.
Token Format Cheat Sheet
| Token | Format | Example |
|-------|--------|---------|
| Mind Key | + 36 chars | |
| JWT | + base64 | |
| Computer Token | + 36 chars | |
Next Steps
- Authentication — full auth guide
- User & Minds API — JWT-protected endpoints
- Memory API — Mind Key-protected endpoints
────────────────────────────────────────────────────────────
# Quick Start for LLM Agents
SUMMARY: In 3 API calls: recall all memories, store a new one, search. The essential LLM workflow.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start for LLM Agents
You lose all memory between sessions. Synapse is your external brain. This guide
shows the three essential API calls every LLM agent must know.
> [!CRITICAL]
> Call at the START of EVERY session.
> Without this call, you have no memory of who the user is, what you've promised,
> or what you were working on last time.
Step 1: Recall All Memories (ALWAYS FIRST)
[CODE BLOCK]
Returns a structured plain-text summary of all stored memories. Parse this to
rebuild your mental model of the user, their projects, and past interactions.
Example response:
[CODE BLOCK]
Step 2: Store a New Memory
When you learn something worth remembering:
[CODE BLOCK]
Categories: , , , , , , , ,
Priorities: , , ,
> [!TIP]
> Always include a field — a short identifier for the memory. This lets you
> update the same memory later by re-POSTing with the same key.
Step 3: Search for a Specific Memory
[CODE BLOCK]
> [!TIP]
> FTS5 syntax: multiple words = AND search. Phrases in quotes: .
> Prefix search: . Boolean: .
Open Tools (No Auth Headers)
If your tool can only open URLs (no custom headers), use the parameter:
[CODE BLOCK]
> [!WARNING]
> is rate-limited to 60 requests/minute. Bearer header has no rate limit.
> Use Bearer header whenever possible.
Complete Session Workflow
1. Session start: — load all memories
2. During work: — find specific facts
3. On new info: — store it (with category, key, tags, priority)
4. Periodically: — check for human messages
5. Session end: Store any final learnings via
Common Patterns
Update an existing memory
POST with the same and — the existing memory is
updated, not duplicated.
Store a project status
[CODE BLOCK]
Record a mistake (so you don't repeat it)
[CODE BLOCK]
Check for human messages
[CODE BLOCK]
Returns unread messages from the human. Reply with:
[CODE BLOCK]
Next Steps
- Authentication — Mind Key vs JWT
- Memory API reference — all 22 memory endpoints
- Chat API — async communication with humans
- LLM Cookbook — practical patterns
────────────────────────────────────────────────────────────
# Quick Start (Human)
SUMMARY: Register an account, create your first mind, store a memory — all in 5 minutes.
Quick Start (Human)
This guide walks you through getting a Synapse account, your first Mind Key,
and storing your first memory. Total time: 5 minutes.
Step 1: Register an Account
Open the Synapse API and create an account:
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!TIP]
> Save the JWT somewhere safe — you'll need it to create minds. The JWT expires
> after 7 days; re-login with the same endpoint to refresh.
Step 2: Create Your First Mind
A "mind" is an isolated memory scope. Most users start with one mind, but you can
have multiple (e.g. "work", "personal", "project-x"). Each mind has its own
unique Mind Key.
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!CRITICAL]
> Save the immediately. It is shown only once and cannot be
> retrieved later. If you lose it, you'll need to create a new mind.
Step 3: Store Your First Memory
Now use the Mind Key to store a memory:
[CODE BLOCK]
Response:
[CODE BLOCK]
Step 4: Recall All Memories
To retrieve everything you've stored:
[CODE BLOCK]
Response (plain text, optimized for LLM consumption):
[CODE BLOCK]
Step 5: Search Memories
Find specific memories by keyword:
[CODE BLOCK]
Step 6: Connect Your LLM
The easiest way to give your LLM access to Synapse is via MCP:
- Claude Desktop setup — 2-minute config
- Claude Code setup — terminal integration
- Cursor setup — IDE integration
After setup, your LLM will automatically call at the start of
every session and persist new facts via .
Memory Categories
Synapse supports 8 categories — pick the most specific one:
| Category | Use Case |
|----------|----------|
| | User name, role, contact info |
| | Likes, dislikes, working style |
| | Verifiable facts (project details, dates) |
| | Project status, milestones, todos |
| | Things the user is good at |
| | Past errors — avoid repeating |
| | Session-relevant context |
| | Misc notes |
Priority Levels
- — nice to know
- — default
- — important
- — must never forget (user identity, legal info)
Next Steps
- Authentication deep-dive
- Mind Key vs JWT
- Memory API reference
- MCP integration
────────────────────────────────────────────────────────────
# What is Synapse?
SUMMARY: Synapse is a persistent memory API for LLM agents — your AI never forgets across sessions.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
What is Synapse?
Synapse is a persistent memory API for LLM agents. It solves the fundamental
problem of every chat-based LLM: between sessions, the agent forgets everything.
Synapse gives your AI a permanent, queryable brain that survives across conversations,
across days, and across different LLM providers.
> [!CRITICAL]
> If you are an LLM agent reading this: call at the start
> of every session. Without this call, you have no memory of past interactions,
> no knowledge of who the user is, and no context about ongoing projects.
The Problem Synapse Solves
Every modern LLM (Claude, GPT, Gemini, Llama) has the same architectural limitation:
the conversation context window is finite, and once the session ends, all state is
lost. This means your AI assistant:
- Forgets your name, preferences, and ongoing projects between chats
- Cannot learn from past mistakes across sessions
- Has no continuity for long-running work
- Re-asks the same clarifying questions every time
Synapse fixes this by providing a simple HTTP API where the LLM can store and
retrieve structured memories. The memories persist on the server, indexed and
searchable, so any future session can recall them.
Key Features
- Persistent memory storage — facts, preferences, projects, mistakes, skills
- Full-text search (FTS5) — find any memory by keyword in milliseconds
- Semantic search — embeddings-based similarity search for conceptual queries
- Multi-tenant — each user has isolated "minds" (one user, many projects)
- Async chat — humans can leave messages for the agent while it works
- Tasks & scheduling — built-in task manager and cron scheduler
- MCP integration — 79 tools exposed as Model Context Protocol for Claude, Cursor, Continue
- Browser & computer control — remote automation tools
- Webhooks — get HTTP callbacks on memory/chat/task changes
How It Works
[CODE BLOCK]
1. The LLM calls at session start
2. Synapse returns a structured text summary of all stored memories
3. The LLM works, periodically calling to store new facts
4. When the user asks a question, the LLM can call
5. At session end, important new context is persisted for the next session
Who Is It For?
- LLM agent developers who need persistent state
- Power users running local LLMs (Ollama, LM Studio) with custom agents
- Teams building AI assistants that need shared memory
- Automation engineers chaining LLM calls across sessions
Quick Comparison
| Feature | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Storage location | OpenAI servers | Your server |
| API access | No (closed) | Yes (REST + MCP) |
| Multi-tenant | No | Yes (minds) |
| Custom categories | No | Yes (8 categories) |
| Search | Limited | FTS5 + semantic |
| Self-hostable | No | Yes (Docker) |
Next Steps
- Quick Start for humans — get a Mind Key in 5 minutes
- Quick Start for LLMs — first API calls
- Authentication — Mind Keys vs JWTs
- Architecture overview — how Synapse is built
## CATEGORY: API REFERENCE
Complete reference for every API endpoint.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Browser automation service — separate Docker container on port 13000 for headless browser control.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Browser Proxy
The Browser Proxy is a separate Docker service that provides headless
browser automation via Playwright. It is NOT part of the Synapse API directly —
Synapse endpoints do not include paths.
Architecture
[CODE BLOCK]
Access Methods
Method 1: Via Synapse MCP Server (recommended)
The Synapse MCP server exposes browser tools as MCP tools. Use this for
LLM-driven browser automation:
[CODE BLOCK]
Available MCP browser tools:
- — open a new browser tab
- — navigate to a URL
- — click an element
- — type text into a field
- — capture a screenshot
- — close the tab
- (and more — see MCP integration)
Method 2: Direct Browser Proxy Access
For non-MCP integrations, connect directly to the browser-proxy service:
[CODE BLOCK]
Common Use Cases
Web scraping
[CODE BLOCK]
Form automation
[CODE BLOCK]
Screenshot capture
[CODE BLOCK]
Related Services
| Service | Port | Purpose |
|---------|------|---------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | MCP server (79 tools) |
| Browser Proxy | 13000 | Headless browser automation |
| SSH Proxy | 12900 | SSH access to remote machines |
Next Steps
- MCP Integration — how to use browser tools via MCP
- Computer Control API — for GUI automation on registered machines
────────────────────────────────────────────────────────────
# Chat API
SUMMARY: Asynchronous chat between humans and LLM agents — poll, reply, history, unread count, file uploads.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
Chat API
The Chat API enables asynchronous messaging between humans and LLM agents.
Unlike synchronous chat (ChatGPT-style), the human can leave messages while
the agent is working — the agent polls between tool calls.
How It Works
[CODE BLOCK]
1. Human sends a message via the web UI (uses JWT)
2. Message is stored, marked as unread
3. Agent polls between tool calls
4. Poll returns all unread messages and marks them as read
5. Agent processes the message, optionally replies via
Endpoints
GET /chat/poll
Poll for new messages from the human. Returns unread messages and marks them
as read. Use this between tool calls.
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /chat/reply
Send a message as the agent.
[CODE BLOCK]
POST /chat/send
Send a message as the human (requires JWT, not Mind Key).
[CODE BLOCK]
GET /chat/history
Get recent chat history (both roles).
[CODE BLOCK]
GET /chat/unread
Get unread message count.
[CODE BLOCK]
GET /chat/status
Get chat session status (last message timestamps, unread counts).
[CODE BLOCK]
POST /chat/upload
Upload a file attachment for a specific message (multipart form).
[CODE BLOCK]
GET /chat/files/:messageid
List file attachments for a message.
[CODE BLOCK]
GET /chat/file/:fileid
Download a file attachment.
[CODE BLOCK]
Polling Pattern
> [!TIP]
> Poll every 30-60 seconds between tool calls. Don't poll more frequently —
> it wastes API quota and provides no benefit.
[CODE BLOCK]
Next Steps
- Tasks API
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Computer Control API
SUMMARY: Remote control of registered computers — queue commands, take screenshots, run scripts on remote machines.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
Computer Control API
The Computer Control API lets you remote-control registered computers. A small
agent () runs on the target machine, polls for commands,
executes them, and posts results back. This enables LLM-driven GUI automation.
Architecture
[CODE BLOCK]
User-Facing Endpoints (Mind Key or JWT)
GET /computers/list
List all registered computers.
[CODE BLOCK]
GET /computers/:id
Get details of a single computer.
[CODE BLOCK]
POST /computers/install-code
Generate an install code for registering a new computer.
[CODE BLOCK]
Response:
POST /computers/:id/commands
Queue a command for the remote agent to execute.
[CODE BLOCK]
Response:
GET /computers/:id/command (via query)
Queue a command via GET (for simple cases).
[CODE BLOCK]
GET /computers/:id/commands
List recent commands for a computer.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Get status + result of a specific command.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: queue a screenshot command and wait up to 30s for the result.
[CODE BLOCK]
POST /computers/:id/disable
Disable a computer (revokes its token, keeps the record for audit).
[CODE BLOCK]
DELETE /computers/:id
Delete a computer permanently.
[CODE BLOCK]
Agent-Facing Endpoints (Computer Token)
These endpoints are used by the running on the target
machine. They use a Computer Token (returned by ), not a
Mind Key.
POST /computers/register
Redeem an install code and get a Computer Token.
[CODE BLOCK]
Response:
> [!CRITICAL]
> Save the — it's shown only once and is required for all
> agent-side endpoints.
GET /computers/me/poll
Long-poll for new commands. The agent calls this in a loop.
[CODE BLOCK]
Returns immediately if commands are pending, or after seconds if not.
POST /computers/me/commands/:cid/result
Post the result of executing a command.
[CODE BLOCK]
Command Types
| Type | Payload | Description |
|------|---------|-------------|
| | | Capture screen as PNG (base64) |
| | | Click at coordinates |
| | | Move mouse to coordinates |
| | | Type text at cursor |
| | | Press key combo |
| | | Scroll wheel |
| | | Drag and drop |
Common Pattern: LLM-Driven GUI Automation
[CODE BLOCK]
Next Steps
- Browser Proxy — separate service for browser automation
- Self-Hosted Agents Guide
────────────────────────────────────────────────────────────
# Cron & Scheduler
SUMMARY: Schedule recurring API calls — cron jobs that fire on a schedule, perfect for periodic sync and reminders.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule formats: integer seconds (e.g. "300"), "*/N * * * *" (every N min), "* */N * * *" (every N hours)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every 5 min, /chat/poll every hour, etc.
Cron & Scheduler
The Cron API lets you schedule recurring HTTP calls to Synapse endpoints (or
external HTTPS endpoints). Perfect for periodic sync, reminders, and
maintenance tasks.
Endpoints
POST /cron
Create a scheduled task.
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /cron
List all scheduled tasks for the authenticated mind.
[CODE BLOCK]
DELETE /cron/:id
Delete a scheduled task.
[CODE BLOCK]
PUT /cron/:id/toggle
Enable or disable a task without deleting it.
[CODE BLOCK]
Schedule Syntax
> [!IMPORTANT]
> Synapse uses a simplified scheduler — NOT full 5-field cron. Only the three formats below are supported. Standard cron expressions like or will be rejected with .
Supported formats
| Format | Example | Meaning |
|--------|---------|----------|
| Integer (seconds) | | Every 300 seconds (5 minutes) |
| | | Every 15 minutes |
| | | Every 2 hours |
NOT supported (will be rejected)
| Schedule | Why it fails |
|----------|-------------|
| | Fixed minute without — use (seconds) instead |
| | Day-of-week ranges not supported |
| | Day-of-month fields not supported |
| | Fixed hour:minute not supported |
Endpoint Restrictions
> [!WARNING]
> Endpoints must be or URLs pointing to:
> - The same Synapse instance (e.g. )
> - Public HTTPS URLs (no private IPs, no localhost, no metadata IPs)
This prevents SSRF attacks where a compromised mind could schedule requests to
internal services.
Common Patterns
Periodic memory recall (every 15 minutes)
[CODE BLOCK]
Hourly chat poll (integer seconds)
[CODE BLOCK]
Bi-daily sync
[CODE BLOCK]
Next Steps
- Variables API
- Webhooks API
────────────────────────────────────────────────────────────
# Errors & Error Handling
SUMMARY: HTTP status codes, error response format, and how to recover from common errors.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Errors & Error Handling
Synapse uses standard HTTP status codes with a consistent error response format.
This page explains how to interpret and recover from errors.
Error Response Format
All errors return JSON with this structure:
[CODE BLOCK]
| Field | Description |
|-------|-------------|
| | HTTP status code |
| | HTTP status name |
| | Human-readable error description |
| | URL to relevant documentation (when applicable) |
HTTP Status Codes
200 OK
Success. The request was processed correctly.
201 Created
Success. A new resource was created (e.g. ).
204 No Content
Success. No body returned (e.g. ).
400 Bad Request
The request was malformed. Common causes:
- Missing required JSON fields
- Invalid JSON syntax
- Invalid enum value (e.g. wrong category)
[CODE BLOCK]
Fix: Check the request body against the API docs. Ensure all required
fields are present and have valid values.
401 Unauthorized
Authentication failed. Common causes:
- Missing header
- Invalid Mind Key or JWT
- Using a Mind Key where a JWT is required (or vice versa)
[CODE BLOCK]
Fix: Verify your token. See Authentication.
403 Forbidden
You're authenticated but not allowed to perform this action. Common causes:
- Trying to delete another user's mind
- Trying to verify a memory with a Mind Key (requires JWT)
- Mind is disabled
Fix: Check if you're using the correct token type for this endpoint.
404 Not Found
The requested path or resource doesn't exist.
> [!CRITICAL]
> Do NOT guess endpoint paths. Only the paths listed in
> exist. If you get a 404, you used a wrong path.
[CODE BLOCK]
Fix: Call to see the list of valid endpoints. Compare
your URL against the list character-by-character.
409 Conflict
The request conflicts with existing state. Common causes:
- Trying to register with an email that already exists
- Duplicate webhook URL
Fix: Use a different value, or use to update the existing resource.
429 Too Many Requests
You hit a rate limit. Only applies to query parameter auth (60/min).
[CODE BLOCK]
Response headers:
[CODE BLOCK]
Fix: Switch to header (no rate limit), or wait
seconds.
500 Internal Server Error
Server error. This shouldn't happen — if it does, it's a bug.
Fix:
1. Retry with exponential backoff (1s, 2s, 4s, 8s)
2. Check to see if the server is up
3. If persistent, report the error
503 Service Unavailable
Server is temporarily down (e.g. during deployment, database migration).
Fix: Wait and retry. Check .
Recovery Patterns
Retry with exponential backoff
[CODE BLOCK]
Auth error handling
[CODE BLOCK]
Common Error Scenarios
"Mind Key fehlt oder ungültig"
- You forgot the header
- You used but the key is wrong
- You're using a JWT where a Mind Key is required
"Route not found"
- You guessed a path that doesn't exist
- You used a verb wrong (e.g. vs )
- Check for valid paths
"Rate limit exceeded"
- You're using and exceeded 60 req/min
- Switch to header
Next Steps
- Authentication
- API Overview
- Rate Limits
────────────────────────────────────────────────────────────
# Memory API
SUMMARY: Complete reference for the 22 memory endpoints: store, recall, search, semantic search, sync, audit, and more.
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
Memory API
The Memory API is the heart of Synapse. It provides 22 endpoints for storing,
retrieving, searching, and managing structured memories. All endpoints require
a Mind Key for authentication.
> [!CRITICAL]
> Always call at the start of every session. This is
> the only way to rebuild context from previous sessions.
Categories
Memories are organized into 8 categories:
| Category | Use Case |
|----------|----------|
| | User name, role, contact info, preferences about self |
| | Likes, dislikes, working style, communication prefs |
| | Verifiable facts (project details, dates, URLs) |
| | Project status, milestones, architecture |
| | Things the user is good at |
| | Past errors — avoid repeating |
| | Session-relevant context |
| | Misc notes |
Priorities
- — nice to know
- — default
- — important
- — must never forget (user identity, legal info)
Core Endpoints
GET /memory/recall
Returns ALL memories as LLM-optimized plain text. Call this at every session start.
[CODE BLOCK]
Response (text/plain):
[CODE BLOCK]
POST /memory
Store a new memory or update an existing one (same category + key = update).
[CODE BLOCK]
Response:
GET /memory
List memories with optional filters.
[CODE BLOCK]
PUT /memory/:id
Update a specific memory by ID.
[CODE BLOCK]
DELETE /memory/:id
Delete a single memory.
[CODE BLOCK]
Search Endpoints
GET /memory/search
Full-text search using FTS5.
[CODE BLOCK]
FTS5 syntax:
- Multiple words = AND:
- Phrase:
- Prefix:
- Boolean:
- Exclude:
GET /memory/semantic-search
Conceptual search using embeddings (slower than FTS5 but understands meaning).
[CODE BLOCK]
Returns memories that are semantically similar to the query, even if no keywords
match. Useful for "find memories about X" where X is described differently.
GET /memory/by-tag
List memories by tag.
[CODE BLOCK]
GET /memory/related/:id
Find memories related to a specific memory (via shared tags).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Incremental sync — returns memories changed since a timestamp.
[CODE BLOCK]
Response:
POST /memory/sync
Apply a diff from another instance (for self-hosted sync).
[CODE BLOCK]
Bulk Operations
POST /memory/bulk-delete
Delete multiple memories by ID.
[CODE BLOCK]
POST /memory/embed-batch
Generate embeddings for memories that don't have them yet (for semantic search).
[CODE BLOCK]
GET /memory/embed-batch-status
Check embedding generation progress.
[CODE BLOCK]
Verification
Memories have a flag. Agent-stored memories default to unverified
(); human-stored memories are verified ().
POST /memory/verify
Mark a memory as verified (requires JWT, not Mind Key).
[CODE BLOCK]
POST /memory/unverify
Mark a memory as unverified (requires JWT).
[CODE BLOCK]
GET /memory/unverified
List memories awaiting human verification.
[CODE BLOCK]
Statistics & Audit
GET /memory/stats
Aggregate statistics for the current mind.
[CODE BLOCK]
Returns:
GET /memory/audit
Audit log of all state-changing operations.
[CODE BLOCK]
GET /memory/contradictions
Detect potential contradictions in stored memories.
[CODE BLOCK]
GET /memory/expiring
List memories with expiry dates approaching.
[CODE BLOCK]
Health & Export
GET /memory/health
Quick health check for memory system.
[CODE BLOCK]
GET /memory/mind-export
Full JSON export of all memories (for backup).
[CODE BLOCK]
POST /memory/compact
Compact similar memories (auto-summarization).
[CODE BLOCK]
Next Steps
- Quick Start for LLMs
- Memory Best Practices
- FTS5 Search
- Semantic Search
────────────────────────────────────────────────────────────
# API Overview & Base URL
SUMMARY: All Synapse API endpoints, base URL, auth patterns, and response formats at a glance.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
API Overview & Base URL
The Synapse API is a RESTful HTTP API. All endpoints return JSON (except where
noted). This page covers the essentials you need before diving into specific
endpoints.
Base URL
[CODE BLOCK]
All paths in this documentation are relative to this base URL. For self-hosted
instances, replace with your own URL.
Authentication
Two methods, both sent via header:
[CODE BLOCK]
Or via query parameter (rate-limited to 60/min):
[CODE BLOCK]
See Authentication for details.
Endpoint Groups
| Group | Auth | Description |
|-------|------|-------------|
| Public | None | Landing page, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, search, sync, embeddings |
| Chat | Mind Key / JWT | Async messaging between human and agent |
| Tasks | Mind Key | Task management |
| Scripts | Mind Key / JWT | Persistent script store |
| Scheduler | Mind Key | Cron jobs + variables |
| Webhooks | Mind Key | HTTP callbacks on events |
| Computers | Mind Key / JWT | Remote computer control |
| User/Minds | JWT | Account + mind management |
| Sharing | JWT | Mind sharing between users |
| Push | JWT | Web Push subscriptions |
| Tools | None | Time, calc, random (public utilities) |
Response Formats
- JSON (default):
- Plain text: returns LLM-optimized text
- HTML: , , , ,
Standard Response Envelope
Success responses return the data directly:
[CODE BLOCK]
Error responses use this format:
[CODE BLOCK]
> [!NOTE]
> The field links to relevant documentation for common errors.
HTTP Status Codes
| Code | Meaning |
|------|---------|
| 200 | Success (GET, PUT) |
| 201 | Created (POST) |
| 204 | No content (DELETE) |
| 400 | Bad request (validation error) |
| 401 | Unauthorized (missing/invalid token) |
| 403 | Forbidden (wrong token type) |
| 404 | Not found (path doesn't exist) |
| 409 | Conflict (duplicate) |
| 429 | Too many requests (rate limit) |
| 500 | Server error |
Discoverability Endpoints
| Endpoint | Purpose |
|----------|---------|
| | Landing page (LLM-optimized) |
| | Machine-readable list of all endpoints |
| | Plain-text endpoint list |
| | OpenAPI 3.0 specification |
| | Full API documentation (HTML) |
| | API docs as JSON |
| | Documentation system (HTML) |
| | Documentation index (JSON) |
| | All docs as one text block |
| | Interactive API playground |
Rate Limits
| Auth Method | Limit |
|-------------|-------|
| Mind Key (header) | None |
| Mind Key (?key=) | 60/min per IP |
| JWT (header) | None |
| Public endpoints | None |
Rate-limited responses include:
[CODE BLOCK]
Pagination
List endpoints support and :
[CODE BLOCK]
Default limit: 100. Max limit: 500.
CORS
All endpoints support CORS for browser-based clients:
[CODE BLOCK]
SDKs & Clients
- Node.js SDK: (repo)
- MCP Server: (repo)
- HTTP client: any HTTP library (curl, fetch, axios, etc.)
Next Steps
- Memory API — the most important endpoints
- Chat API — async human-agent communication
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Rate Limits & Quotas
SUMMARY: Rate limit policies for Synapse API — Bearer header (unlimited), ?key= (60/min), public endpoints.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Rate Limits & Quotas
Synapse has a simple, predictable rate limit policy designed to prevent abuse
while not getting in the way of legitimate usage.
Rate Limit Policy
| Auth Method | Limit | Scope |
|-------------|-------|-------|
| Mind Key () | None | Per-mind |
| Mind Key () | 60 req/min | Per-IP |
| JWT () | None | Per-user |
| Public endpoints | None | Global |
> [!TIP]
> Always use the header when possible. It has no
> rate limit. Use only for tools that can't set custom headers.
Rate Limit Headers
When you use auth, responses include rate limit headers:
[CODE BLOCK]
When you exceed the limit:
[CODE BLOCK]
When You Hit a Rate Limit
If you get a 429:
1. Switch to Authorization header (recommended):
[CODE BLOCK]
2. Or wait seconds and retry.
Why the ?key= Limit Exists
The query parameter is convenient for URL-only tools (browsers,
commands), but it has security and performance implications:
- Security: Query parameters are logged in server access logs, browser
history, and Referer headers. Limiting usage reduces exposure.
- Performance: Query-parameter auth requires an IP-based rate limiter
(Redis lookup per request), which adds latency. Header auth skips this.
- Abuse prevention: A leaked URL could be shared and hammered.
The IP limit contains the blast radius.
Recommended Patterns
LLM agents
[CODE BLOCK]
Browser-based tools
If your tool can only open URLs:
[CODE BLOCK]
MCP server
MCP servers always use header auth via env var — no rate
limit applies.
Bulk imports
For bulk operations (e.g. importing 1000 memories), always use header auth.
Bulk imports via will hit the rate limit within 1 minute.
Quotas (Mind-Level)
There are currently no per-mind quotas on storage size or memory count. All
limits are at the auth/IP level, not the data level. This may change in the
future for multi-tenant fairness.
Monitoring Your Usage
[CODE BLOCK]
Next Steps
- Authentication
- Errors & Error Handling
────────────────────────────────────────────────────────────
# Scripts API
SUMMARY: Persistent script store — save reusable shell, Python, or Node scripts and fetch them via curl | bash.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
Scripts API
The Scripts API provides a persistent store for reusable scripts. Scripts are
named and versioned within a mind, and can be fetched as plain text — perfect
for patterns.
Endpoints
POST /script
Store or update a script.
[CODE BLOCK]
GET /script/:name
Fetch script content as . Perfect for piping to bash.
[CODE BLOCK]
GET /script/:name/info
Get script metadata without the content.
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /scripts
List all scripts in the current mind.
[CODE BLOCK]
DELETE /script/:name
Delete a script.
[CODE BLOCK]
Common Use Cases
Deployment scripts
Store standard deployment procedures so the LLM can run them without
re-deriving the steps each time:
[CODE BLOCK]
Troubleshooting snippets
Store diagnostic commands for common issues:
[CODE BLOCK]
Configuration generators
Store scripts that generate configs:
[CODE BLOCK]
Next Steps
- Variables API
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Tasks API
SUMMARY: Task management for LLM agents — create, list, update, complete, delete tasks with priorities.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
Tasks API
The Tasks API gives LLM agents a structured way to track multi-step work.
Tasks are scoped to the current mind and persist across sessions, so the agent
can resume work where it left off.
Endpoints
GET /mind/tasks
List all tasks for the current mind.
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /mind/task
Create a new task.
[CODE BLOCK]
GET /mind/task (query params)
Create a task via GET (for URL-only tools).
[CODE BLOCK]
PUT /mind/task/:id
Update an existing task.
[CODE BLOCK]
GET /mind/task/:id/complete
Mark a task as done.
[CODE BLOCK]
GET /mind/task/:id/delete
Delete a task permanently.
[CODE BLOCK]
Priorities
- — non-urgent
- — default
- — important
- — must do immediately
Statuses
- — created, not started
- — currently being worked on
- — completed
- — abandoned
Pattern: Task-Driven Workflow
[CODE BLOCK]
Next Steps
- Task-Driven Workflow
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Utility Tools (time, calc, random)
SUMMARY: Public utility endpoints — server time, safe calculator, random value generator. No auth required.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Utility Tools
The endpoints are public utilities — no authentication required.
They're useful for LLM agents that need server-side time, safe math, or random
values.
GET /tools/time
Get the current server time, timezone, and UTC offset.
[CODE BLOCK]
Response:
[CODE BLOCK]
Use case: LLM agents that need to know "what time is it now" for scheduling,
timestamps, or relative date calculations.
GET /tools/calc
Safe calculator — arithmetic only, no . Supports , , , ,
, , , and numbers.
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!TIP]
> Use this instead of trying to do math in your head or via string parsing.
> It's safe (no code injection possible) and accurate.
Supported operators
- addition
- subtraction
- multiplication
- division
- modulo
- parentheses
- Numbers (integers and decimals)
Examples
[CODE BLOCK]
GET /tools/random
Generate random values.
[CODE BLOCK]
Type parameters
| Type | Parameters | Output |
|------|-----------|--------|
| | none | UUID v4 string |
| | , (default 0-100) | Integer |
| | , (default 0-100) | Float |
| | , (length range, default 8-16) | Hex string |
| | , (length range, default 8-16) | Alphabetic string |
Use Cases for LLM Agents
Generate unique IDs
[CODE BLOCK]
Calculate percentages
[CODE BLOCK]
Get current timestamp
[CODE BLOCK]
Generate test data
[CODE BLOCK]
Next Steps
- API Overview — all endpoint groups
- Errors & Error Handling
────────────────────────────────────────────────────────────
# User & Minds API
SUMMARY: Account management — register, login, create minds, list minds, delete minds. JWT-protected.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
User & Minds API
The User & Minds API handles account management. These endpoints use JWT
authentication (not Mind Keys) because they operate at the account level, not
the mind level.
Authentication Endpoints
POST /register
Create a new user account.
[CODE BLOCK]
Response:
[CODE BLOCK]
POST /login
Login to an existing account.
[CODE BLOCK]
Response: same as .
Minds Endpoints
POST /minds
Create a new mind. Returns the Mind Key — save it immediately, it's shown
only once.
[CODE BLOCK]
Response:
[CODE BLOCK]
> [!CRITICAL]
> The is shown only once. If you lose it, you cannot retrieve it —
> you must delete the mind and create a new one (which loses all stored memories).
GET /minds
List all minds for the current user.
[CODE BLOCK]
Response:
[CODE BLOCK]
DELETE /minds/:id
Delete a mind permanently.
[CODE BLOCK]
> [!WARNING]
> Deleting a mind is irreversible. All memories, tasks, chat history, and
> scripts in that mind are permanently lost. Export first via
> if you need a backup.
Multi-Mind Pattern
Most users benefit from multiple minds to keep contexts isolated:
[CODE BLOCK]
Use different Mind Keys in different LLM sessions to keep contexts isolated.
Account Security
Password requirements
- Minimum 6 characters
- No maximum (use a password manager)
- Stored as bcrypt hash (never plaintext)
JWT expiry
JWTs expire after 7 days. When expired, simply call again.
Mind Key security
Mind Keys never expire. If a Mind Key is compromised:
1. Create a new mind via
2. Update your LLM config with the new Mind Key
3. Delete the compromised mind via
Next Steps
- Authentication — full auth guide
- Mind Key vs JWT — decision guide
- Sharing API — share minds with other users
────────────────────────────────────────────────────────────
# Variables API
SUMMARY: Fast key-value store for LLM state — counters, flags, last-seen timestamps, partial progress.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
Variables API
The Variables API is a fast key-value store for ephemeral state. Unlike
memories (which are indexed, searchable, and structured), variables are
optimized for quick read/write access — perfect for counters, flags, and
session state.
Endpoints
POST /var
Set or update a variable.
[CODE BLOCK]
GET /var/:key
Get a single variable.
[CODE BLOCK]
Response:
[CODE BLOCK]
GET /var
List all variables.
[CODE BLOCK]
DELETE /var/:key
Delete a variable.
[CODE BLOCK]
When to Use Variables vs Memory
| Use Case | Use |
|----------|-----|
| User name, preferences | Memory (searchable, structured) |
| Last session timestamp | Variable (ephemeral state) |
| Counter (e.g. messages sent) | Variable (frequent updates) |
| Workflow state ("step 3 of 5 done") | Variable (transient) |
| Long-form project notes | Memory (full-text indexed) |
| Reusable scripts | Script store (named, versioned) |
Common Patterns
Track last session
[CODE BLOCK]
Counter pattern
[CODE BLOCK]
Feature flags
[CODE BLOCK]
Next Steps
- Memory API — for structured, searchable data
- Cron & Scheduler
────────────────────────────────────────────────────────────
# Webhooks
KEY CONTEXT:
Webhook management via REST API. Create, list, get, delete, enable/disable and test webhooks. Events: memory.created, memory.updated, memory.deleted, memory.verified, memory.unverified, task.updated, chat.message_sent. Webhooks fire HTTP POST to configured URL with HMAC-SHA256 signature.
Webhooks
Overview
Webhooks allow you to receive HTTP callbacks when events occur in your Synapse mind. When an event triggers, Synapse sends a request to the URL you configured, with a JSON body containing event data and a HMAC-SHA256 signature for verification.
Webhooks have a 20 webhooks per mind limit.
Events
| Event | Description |
|-------|-------------|
| | Fired when a new memory is stored |
| | Fired when a memory is updated |
| | Fired when a memory is deleted |
| | Fired when a memory is verified |
| | Fired when a memory is unverified |
| | Fired when a scheduled task status changes |
| | Fired when a chat message is sent |
Create Webhook
Create a new webhook for the authenticated mind.
Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| | string | yes | The URL to call when the event fires. Must be HTTPS (or for development). |
| | string | yes | Comma-separated event patterns. Use for all events. Examples: , |
| | string | yes | Secret for HMAC-SHA256 signature verification. |
Response
| Field | Type | Description |
|-------|------|-------------|
| | string (UUID) | Webhook ID |
| | string | Webhook URL |
| | string | Event pattern (e.g. ) |
| | string (UUID) | Mind that owns this webhook |
| | boolean | Whether the webhook is enabled |
| | number | Unix timestamp (seconds) |
List Webhooks
Lists all webhooks for the authenticated mind.
Response
Array of webhook objects with the following fields:
| Field | Type | Description |
|-------|------|-------------|
| | string (UUID) | Webhook ID |
| | string | Webhook URL |
| | string | Event pattern (e.g. ) |
| | string (UUID) | Mind that owns this webhook |
| | boolean | Whether the webhook is enabled |
| | number | Unix timestamp (seconds) |
| | number or null | Unix timestamp of last call |
| | number or null | HTTP status code of last call |
| | string or null | Error message from last call |
Get Webhook
Gets a single webhook by ID. Requires ownership.
Response
Same fields as List.
Update Webhook
Update a webhook's URL, events, or secret. Requires ownership.
Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| | string | no | New webhook URL |
| | string | no | New event patterns |
| | string | no | New secret |
Enable / Disable Webhook
Enable a webhook. Requires ownership.
Disable a webhook. Requires ownership.
Test Webhook
Sends a test event () to the webhook URL. Requires ownership.
Delete Webhook
Delete a webhook by ID. Requires ownership.
Example
[CODE BLOCK]
Response
[CODE BLOCK]
Signature Verification
The webhook payload includes an HMAC-SHA256 signature in the header. The signature is computed over the raw request body bytes (not parsed-then-restringified JSON).
[CODE BLOCK]
Limits & Auto-Disable
- Rate Limit: 20 webhooks per mind.
- Auto-Disable: A webhook returning HTTP 410 (Gone) is automatically disabled. This allows remote services to signal "stop sending" without deleting the webhook configuration.
Deprecated Event Names
| Old Name | New Name |
|----------|----------|
| | |
| | |
| | |
## CATEGORY: MCP INTEGRATION
Integration with Claude, Cursor, and other MCP clients.
────────────────────────────────────────────────────────────
# MCP in Claude Code
SUMMARY: Use Synapse tools from the Claude Code terminal agent — persistent memory for coding sessions.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP in Claude Code
Claude Code is Anthropic's terminal-based coding agent. With Synapse MCP,
Claude Code gains persistent memory across coding sessions — it remembers
your project context, past decisions, and codebase patterns.
Setup
Method 1: CLI Command (recommended)
[CODE BLOCK]
Method 2: Edit Config File
Edit :
[CODE BLOCK]
Verify It Works
Start Claude Code:
[CODE BLOCK]
In the Claude Code prompt, type:
[CODE BLOCK]
Claude should call and respond with your stored memories.
Common Patterns
Project context persistence
At the start of a coding session:
[CODE BLOCK]
Claude calls , sees your project list, and continues work
where you left off.
Codebase decisions
When you make an architectural decision:
[CODE BLOCK]
Claude calls with category , priority .
Avoiding past mistakes
[CODE BLOCK]
Claude searches memories with category and reminds you of past errors.
Task tracking
[CODE BLOCK]
Claude calls , and the task persists across sessions.
Tool Profiles
For coding sessions where you don't need all 119 tools:
[CODE BLOCK]
Troubleshooting
MCP server not starting
[CODE BLOCK]
Mind Key not recognized
[CODE BLOCK]
Claude Code doesn't see tools
- Restart Claude Code after config changes
- Check to verify Synapse is registered
- See MCP Troubleshooting
Next Steps
- Claude Desktop Setup
- Cursor Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# MCP in Claude Desktop
SUMMARY: Connect Synapse to Claude Desktop in 2 minutes. Claude gets 79 Synapse tools natively.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP in Claude Desktop
Claude Desktop is Anthropic's desktop app for macOS and Windows. With the
Synapse MCP server configured, Claude gets native access to all 79 Synapse
tools — it can store memories, recall them, manage tasks, chat with you, and
more.
Prerequisites
- Claude Desktop app (macOS or Windows)
- Node.js 18+ installed ()
- Your Synapse Mind Key
Step 1: Open the Config File
- macOS:
- Windows:
If the file doesn't exist, create it.
Step 2: Add Synapse MCP Server
[CODE BLOCK]
> [!TIP]
> If you already have other MCP servers configured, just add the
> block inside the existing object.
Step 3: Restart Claude Desktop
1. Fully quit Claude Desktop (Cmd+Q on macOS, not just close window)
2. Reopen Claude Desktop
3. Start a new chat
4. Look for the 🔌 plug icon in the bottom-left — it should say "79 tools"
Step 4: Test It
In a new chat, type:
[CODE BLOCK]
Claude should call the tool and respond with a summary of your
stored memories (or "No memories yet" if your mind is empty).
Available Tools (Selection)
| Tool | Description |
|------|-------------|
| | Recall all memories |
| | Store a new memory |
| | Search memories |
| | List tasks |
| | Create a task |
| | Check for new messages |
| | Reply to a message |
| | Open a browser tab |
| | List registered computers |
Full list: What is MCP?
Troubleshooting
No tools appear in Claude Desktop
1. Verify Node.js version: (must be ≥ 18)
2. Check the config file is valid JSON (no trailing commas)
3. Restart Claude Desktop fully (Cmd+Q, not just close)
4. Check Claude Desktop logs: (macOS)
"Mind Key invalid" error
- Verify starts with
- Get a fresh key via (requires JWT from )
- No quotes around the key in the JSON
npx not found
- Install Node.js 18+:
- Restart terminal after install
- On macOS with Homebrew:
Tools show but calls fail
- Check is reachable:
- Verify your Mind Key works:
- See MCP Troubleshooting
Tool Profiles (Save Tokens)
If you're using a smaller LLM or want to save context tokens, set a tool profile:
[CODE BLOCK]
Profiles: (8 tools), (25), (119, default).
Next Steps
- Claude Code Setup
- Cursor Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# MCP in Continue.dev
SUMMARY: Connect Synapse to Continue.dev — open-source AI coding assistant for VS Code and JetBrains.
MCP in Continue.dev
Continue.dev is an open-source AI coding assistant for VS Code and JetBrains
IDEs. With Synapse MCP, Continue gains persistent memory across sessions.
Prerequisites
- VS Code or JetBrains IDE
- Continue.dev extension installed
- Node.js 18+
- Your Synapse Mind Key
Setup
Step 1: Open Continue Config
In VS Code or JetBrains:
1. Open the Continue extension sidebar
2. Click the gear icon → "Open config.json"
Or edit directly.
Step 2: Add Synapse MCP Server
[CODE BLOCK]
Step 3: Reload Continue
Reload the VS Code window (Cmd+Shift+P → "Reload Window") or restart your IDE.
Verify It Works
In the Continue chat:
[CODE BLOCK]
Continue should call and respond with your stored memories.
Common Patterns
Project context
[CODE BLOCK]
Continue calls , sees your project memories, and continues
work where you left off.
Code review patterns
[CODE BLOCK]
Continue finds your stored code review patterns and applies them.
Pair programming memory
[CODE BLOCK]
Continue stores it as a memory.
Troubleshooting
MCP server not connecting
1. Check is valid JSON
2. Verify Node.js:
3. Check Continue's output panel (View → Output → Continue)
4. Restart IDE
Tools not appearing
- Verify Continue version supports MCP (≥ 0.9.x)
- Check env var is set in the config
- Look for MCP errors in Continue's logs
Next Steps
- Claude Desktop Setup
- Custom MCP Client
────────────────────────────────────────────────────────────
# MCP in Cursor
SUMMARY: Connect Synapse to Cursor IDE for persistent project memory across coding sessions.
MCP in Cursor
Cursor is an AI-powered IDE based on VS Code. With Synapse MCP, Cursor gains
persistent memory across sessions — it remembers your project decisions,
codebase patterns, and past debugging sessions.
Prerequisites
- Cursor IDE installed ()
- Node.js 18+
- Your Synapse Mind Key
Setup
Step 1: Open Cursor Settings
In Cursor:
1. Open Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux)
2. Search for "MCP" or navigate to
Step 2: Add Synapse MCP Server
Click "Add MCP Server" and configure:
| Field | Value |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Step 3: Edit config.json directly (alternative)
Cursor stores MCP config in :
[CODE BLOCK]
Step 4: Restart Cursor
Fully restart Cursor (Cmd+Q and reopen on macOS).
Verify It Works
In Cursor's chat panel (Cmd+L):
[CODE BLOCK]
Cursor should call and respond with your stored memories.
Common Patterns
Project onboarding
When opening a new project:
[CODE BLOCK]
Cursor calls and continues work where you left off.
Architecture decisions
[CODE BLOCK]
Cursor stores it as a memory with priority.
Debugging history
[CODE BLOCK]
Cursor searches for memories and reminds you of past fixes.
Cross-session code patterns
[CODE BLOCK]
Cursor finds memories about auth implementations you've done before.
Troubleshooting
MCP server not connecting
1. Verify Node.js: (≥ 18)
2. Test MCP server: (should start without errors)
3. Check Cursor's MCP logs (View → Output → MCP)
4. Restart Cursor fully
Tools not appearing
- Check is valid JSON
- Verify env var is set
- Check Cursor version supports MCP (≥ 0.42)
Mind Key invalid
[CODE BLOCK]
Next Steps
- Claude Desktop Setup
- Continue.dev Setup
- Persistent LLM Agent Guide
────────────────────────────────────────────────────────────
# Build a Custom MCP Client
SUMMARY: Connect to the Synapse MCP server from your own application using the MCP SDK.
Build a Custom MCP Client
If you're building your own LLM application, you can connect to the Synapse
MCP server directly using the official MCP SDK. This gives your app access to
all 79 Synapse tools.
SDKs
| Language | Package |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
TypeScript Example
Install
[CODE BLOCK]
Connect via stdio
[CODE BLOCK]
Connect via HTTP/SSE (remote)
[CODE BLOCK]
Python Example
Install
[CODE BLOCK]
Connect via stdio
[CODE BLOCK]
Tool Profiles
When connecting, you can request a specific tool profile via the
header (HTTP/SSE) or env var (stdio):
[CODE BLOCK]
Error Handling
[CODE BLOCK]
Use Cases
- Custom AI assistants — build your own agent with persistent memory
- Workflow automation — chain Synapse tools in custom workflows
- Data pipelines — extract memories, transform, load elsewhere
- Monitoring dashboards — display memory stats, chat history, tasks
Next Steps
- MCP Specification
- Synapse MCP Repo
- API Overview
────────────────────────────────────────────────────────────
# MCP Troubleshooting
SUMMARY: Solve common MCP integration issues — server not starting, tools not appearing, auth errors.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
MCP Troubleshooting
Common issues and solutions when integrating Synapse MCP with your LLM client.
Quick Diagnostic Checklist
1. ✅ Node.js 18+ installed? ()
2. ✅ Mind Key starts with ? (not JWT )
3. ✅ Synapse API reachable? ()
4. ✅ Mind Key works? ()
5. ✅ Config file is valid JSON? (no trailing commas, no comments)
6. ✅ Client restarted after config change?
7. ✅ MCP server starts manually? ()
Issue: No Tools Appear in Client
Symptoms
- Claude Desktop / Cursor / Continue shows 0 tools
- No 🔌 icon or "synapse" entry in MCP servers list
Solutions
1. Restart client fully — Cmd+Q on macOS (not just close window)
2. Check config file location:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Validate JSON — paste config into
4. Check client logs for MCP errors:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Run MCP server manually to see startup errors:
[CODE BLOCK]
Issue: "Mind Key invalid" Error
Symptoms
- Tools appear but calls fail with "401 Unauthorized"
- Error: "Mind Key fehlt oder ungültig"
Solutions
1. Verify Mind Key format — starts with , 40 characters
2. Test directly:
[CODE BLOCK]
3. Check env var is set — for stdio transport, the env var must be in the
MCP server config, not your shell
4. Get a fresh Mind Key:
[CODE BLOCK]
Issue: npx Not Found
Symptoms
- Error: "npx: command not found"
- MCP server fails to start
Solutions
1. Install Node.js 18+:
- macOS: or download from
- Linux:
- Windows: download from
2. Restart terminal after install
3. Verify:
Issue: SYNAPSEURL Unreachable
Symptoms
- MCP server starts but tool calls time out
- Error: "fetch failed" or "ECONNREFUSED"
Solutions
1. Test connectivity:
[CODE BLOCK]
2. Check corporate firewall — may block outbound HTTPS
3. Try alternative URL:
- Production:
- MCP server:
4. For self-hosted: ensure your Synapse instance is running and accessible
Issue: MCP Server Crashes
Symptoms
- MCP server exits immediately after start
- Client logs show "MCP server disconnected"
Solutions
1. Run manually to see error:
[CODE BLOCK]
2. Check for port conflicts — MCP server uses port 13100 by default
3. Clear npx cache:
[CODE BLOCK]
4. Update to latest:
[CODE BLOCK]
Issue: Tool Calls Return 429
Symptoms
- Error: "Rate limit exceeded"
Solutions
This shouldn't happen with MCP (uses header auth, no rate limit). If it does:
1. Check if you're using somewhere — switch to header auth
2. Verify — make sure it points to the right instance
3. Contact support if issue persists
Issue: Tools Appear but Don't Work
Symptoms
- Tools listed in client
- Calling a tool returns an error or no result
Solutions
1. Check the tool name — must be exact (e.g. , not )
2. Verify arguments — check the tool's input schema
3. Test via direct API:
[CODE BLOCK]
4. Check Synapse health:
[CODE BLOCK]
Getting Help
If none of the above solves your issue:
1. Check existing issues:
2. Open a new issue with:
- MCP server version ()
- Client name and version
- Operating system
- Relevant log excerpts
- Steps to reproduce
Next Steps
- Claude Desktop Setup
- Claude Code Setup
- API Errors
────────────────────────────────────────────────────────────
# What is MCP?
SUMMARY: Model Context Protocol lets LLMs call external tools. Synapse exposes 79 tools via official MCP server.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
What is MCP?
The Model Context Protocol (MCP) is an open standard by Anthropic (2024)
that lets LLMs call external tools in a structured way. Instead of pasting API
docs into the prompt, you register tools with the MCP server, and the LLM
calls them as needed — like function calling, but standardized and
client-agnostic.
Synapse MCP Server
Synapse ships an official MCP server ( on npm) that exposes
79 tools covering all Synapse features:
| Category | Tools | Count |
|----------|-------|-------|
| Memory | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Total | | 79+ |
How It Works
[CODE BLOCK]
1. You configure your LLM client (Claude Desktop, Cursor, etc.) to use the Synapse MCP server
2. The client starts the MCP server (via )
3. The MCP server connects to Synapse API using your Mind Key
4. The LLM sees all 79 tools as native functions it can call
5. When the LLM needs to remember something, it calls — the MCP server translates this to on Synapse
Transports
The Synapse MCP server supports three transports:
stdio (local, recommended for desktop)
[CODE BLOCK]
HTTP/SSE (remote, multi-tenant)
Connect your MCP client to:
[CODE BLOCK]
WebSocket (mobile, high-volume)
[CODE BLOCK]
Tool Profiles (v1.4.0)
To reduce token overhead for smaller LLMs, the MCP server supports three
tool profiles:
| Profile | Tools | Tokens | Best For |
|---------|-------|--------|----------|
| | 8 (composite dispatch) | 500 | Self-hosted LLMs with ≤8k context |
| | 25 (named) | 2,500 | Mid-size LLMs (Claude Haiku, GPT-3.5) |
| | 119 (all) | 8,250 | Large LLMs (Claude Sonnet/Opus, GPT-4) — default |
Control via:
- Env var:
- Header:
Supported Clients
- Claude Desktop — Anthropic's desktop app
- Claude Code — terminal coding agent
- Cursor — AI-powered IDE
- Continue.dev — open-source AI coding assistant
- Cline — VS Code extension
- Any MCP-compatible client
Why Use MCP Instead of Direct API?
| Approach | Pros | Cons |
|----------|------|------|
| Direct API | Simple, no extra layer | LLM needs to know URLs, headers, auth |
| MCP | LLM sees native tools, no URL memorization | Extra MCP server process |
For most LLM agent use cases, MCP is the better choice — the LLM doesn't need
to remember API paths or auth patterns.
Next Steps
- Claude Desktop Setup — 2-minute config
- Claude Code Setup — terminal integration
- Custom MCP Client — build your own
## CATEGORY: GUIDES & HOW-TOS
Step-by-step guides for concrete scenarios.
────────────────────────────────────────────────────────────
# Automated iOS App Testing
SUMMARY: Use Synapse + Computer Control API to automate iOS app testing via Simulator.
Automated iOS App Testing
Combine Synapse's memory system with the Computer Control API to build
LLM-driven iOS app tests. The LLM remembers test scenarios, learns from past
failures, and adapts to UI changes.
Architecture
[CODE BLOCK]
Prerequisites
- Synapse account + Mind Key
- Synapse MCP server configured in Claude Desktop
- iOS Simulator with installed
- Computer registered in Synapse (see Computer Control API)
Step 1: Register the Simulator Computer
On the Mac running iOS Simulator:
[CODE BLOCK]
Step 2: Store Test Scenarios in Memory
Store reusable test scenarios as memories:
[CODE BLOCK]
Step 3: LLM-Driven Test Execution
In Claude Desktop (with Synapse MCP configured):
[CODE BLOCK]
Claude will:
1. Call to find the memory
2. Call to see the current state
3. Execute each step via (click, type)
4. Verify results via screenshots
5. Store any failures as memories
Step 4: Self-Healing Tests
When a test fails, store the failure and the recovery:
[CODE BLOCK]
Next time the LLM runs the test, it recalls the failure and applies the
recovery automatically.
Step 5: Test Result Tracking
Track test runs as tasks:
[CODE BLOCK]
Common Commands
| Action | Command |
|--------|---------|
| Launch Simulator | |
| Screenshot | (via Synapse MCP) |
| Tap at (x,y) | |
| Type text | |
| Press Home | |
Best Practices
> [!TIP]
> - Store UI coordinates as memories — UI changes, but the LLM can re-learn
> - Use accessibility labels — more stable than coordinates
> - Store test data separately — use variables for usernames, passwords
> - Run tests in clean state — reset Simulator between runs
> - Log screenshots for failures — useful for debugging
Next Steps
- Self-Healing Tests
- Computer Control API
- Memory Best Practices
────────────────────────────────────────────────────────────
# Backup & Restore
SUMMARY: Export your memories for backup, migrate between minds, restore after data loss.
Backup & Restore
Synapse provides full export/import for memory backup, migration, and disaster
recovery. This guide covers the essential operations.
Export
Full Mind Export
Export all memories in a mind as JSON:
[CODE BLOCK]
Response format:
[CODE BLOCK]
Incremental Export (Diff)
Export only memories changed since a timestamp:
[CODE BLOCK]
Response:
[CODE BLOCK]
Automated Backups
Schedule daily backups via cron:
[CODE BLOCK]
> [!NOTE]
> The cron endpoint receives the response but doesn't store it. For real
> backups, point the cron at your own backup server that saves the response.
Better: External Backup Script
[CODE BLOCK]
Add to crontab:
[CODE BLOCK]
Restore
Restore to Same Mind
[CODE BLOCK]
Restore to New Mind
[CODE BLOCK]
Python Restore Script
[CODE BLOCK]
Migration Between Minds
[CODE BLOCK]
Backup Other Data
Don't forget to back up:
| Data Type | Endpoint |
|-----------|----------|
| Memories | |
| Tasks | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variables | |
| Chat history | |
Verification
After restore, verify:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Backup daily — automate with cron
> - Test restores — a backup you can't restore is useless
> - Keep multiple versions — at least 30 days
> - Store offsite — S3, Backblaze B2, etc.
> - Encrypt sensitive backups — memories may contain PII
> - Document the restore process — you'll forget it by the time you need it
Next Steps
- Memory API
- Cron & Scheduler — for automated backups
────────────────────────────────────────────────────────────
# Memory Best Practices
SUMMARY: How to structure memories for effective recall — categories, keys, tags, priorities.
Memory Best Practices
How you structure memories determines how useful they are. This guide covers
patterns for categorizing, tagging, and prioritizing memories so the LLM can
recall the right information at the right time.
Categories: Pick the Most Specific
| Category | Use For | Example |
|----------|---------|---------|
| | User name, role, contact info | |
| | Likes, dislikes, working style | |
| | Verifiable facts | |
| | Project status, decisions | |
| | User's skills | |
| | Past errors to avoid | |
| | Session-relevant context | |
| | Misc notes | |
> [!TIP]
> When in doubt, use for verifiable info and for everything else.
> Don't over-categorize — better to have a clear than a confusing .
Keys: Meaningful Identifiers
The field is the memory's identifier. Use meaningful, stable keys:
Good keys:
-
-
-
-
Bad keys:
- (not meaningful)
- (not descriptive)
- (date doesn't help recall)
Key naming conventions
- (lowercase with underscores)
- Prefix with category: , ,
- Use descriptive nouns, not verbs
- Keep under 50 characters
Tags: For Search and Filtering
Tags enable fast filtering and search. Add 2-5 tags per memory:
[CODE BLOCK]
Tag patterns
- Project names: , ,
- Topics: , , ,
- Status: , ,
- Priority indicators: ,
> [!NOTE]
> Tags are case-insensitive. Use lowercase for consistency.
Priorities: Be Realistic
| Priority | Use For | % of Memories |
|----------|---------|---------------|
| | User identity, legal info, irreversible decisions | 5% |
| | Active projects, important preferences | 20% |
| | Most facts, notes, context | 65% |
| | Ephemeral, nice-to-know | 10% |
> [!WARNING]
> Don't mark everything . If everything is critical, nothing is.
> Reserve for things that would cause real harm if forgotten.
When to Store vs Not Store
Always store
- User identity (name, email, role)
- Long-term preferences
- Project decisions and rationale
- Past mistakes and lessons learned
- Commitments made to the user
Don't store
- Transient state (use variables instead)
- Verbatim conversation history (chat system handles this)
- Sensitive data (passwords, API keys)
- Easily derivable facts (current date, file contents)
- Ephemeral context (use category with low priority)
Updating Memories
POST with the same + updates the existing memory:
[CODE BLOCK]
> [!TIP]
> Use stable keys so you can update without creating duplicates. The LLM
> should re-POST the same key as info changes, not create new memories.
Memory Lifecycle
[CODE BLOCK]
- Create: POST /memory with full context
- Active: Recall frequently, update as needed
- Stale: Still relevant but not actively used (lower priority?)
- Archive: Set priority to , keep for historical reference
- Delete: DELETE /memory/:id when no longer relevant
Periodic cleanup
[CODE BLOCK]
Pattern: Memory Inheritance
For hierarchical context (project → subproject → task):
[CODE BLOCK]
The LLM can then search to find all related memories.
Pattern: Decision Log
Store decisions with rationale so the LLM doesn't re-litigate them:
[CODE BLOCK]
Pattern: Mistake Avoidance
Store mistakes with specific avoidance instructions:
[CODE BLOCK]
Anti-Patterns to Avoid
> [!WARNING]
> - Storing conversation logs — chat system handles this
> - Storing entire files — use script store or external storage
> - Storing ephemeral state — use variables
> - Storing secrets — use environment variables
> - Duplicating memories — use stable keys
> - Over-tagging — 2-5 tags per memory is ideal
> - Everything is critical — be realistic with priorities
Next Steps
- Memory API
- Persistent LLM Agent
- Memory Tagging Strategy
────────────────────────────────────────────────────────────
# Multi-Agent Coordination
SUMMARY: Coordinate multiple LLM agents using shared Synapse minds, tasks, and chat.
Multi-Agent Coordination
When you have multiple LLM agents working on related tasks, Synapse provides
the coordination layer — shared memory, task assignment, and async chat.
Patterns
Pattern 1: Shared Mind (Single Source of Truth)
All agents share one Mind Key. They read/write the same memory store.
[CODE BLOCK]
Use case: Small team of agents working on one project.
Setup:
[CODE BLOCK]
Coordination via tasks:
[CODE BLOCK]
Pattern 2: Specialized Minds (Isolated Contexts)
Each agent has its own mind. They communicate via a shared "coordination" mind.
[CODE BLOCK]
Use case: Agents with different specialties (coding, review, deployment).
Setup:
[CODE BLOCK]
Coordination via shared mind:
[CODE BLOCK]
Pattern 3: Hub-and-Spoke (Orchestrator)
A central orchestrator agent assigns tasks to worker agents.
[CODE BLOCK]
Use case: Complex workflows with parallel work.
Implementation:
[CODE BLOCK]
Coordination via Chat
Agents can communicate via the chat system:
[CODE BLOCK]
> [!NOTE]
> Chat messages are role-tagged. Set role=agent for agent-to-agent messages,
> role=human for human-to-agent.
Coordination via Variables
Use variables for lightweight coordination (locks, flags):
[CODE BLOCK]
Best Practices
> [!TIP]
> - Use separate minds for separate concerns — don't mix coder and reviewer memory
> - Tag agents in chat — for clear addressing
> - Use tasks for work assignment — not chat (chat is for discussion)
> - Implement idempotency — agents may retry failed operations
> - Log everything — store decisions in memory for auditability
Next Steps
- Persistent LLM Agent
- LLM Cookbook
- Webhook Automation
────────────────────────────────────────────────────────────
# Build a Persistent LLM Agent
SUMMARY: Step-by-step guide to building an LLM agent that remembers across sessions using Synapse.
Overview
This guide walks through building an LLM agent that persists context across
sessions using Synapse. By the end, your agent will:
- Recall past context at session start
- Store new learnings as they happen
- Track multi-step tasks across sessions
- Communicate with humans via async chat
Architecture
[CODE BLOCK]
Step 1: Set Up Mind Key
[CODE BLOCK]
Step 2: Session Start Protocol
At the beginning of every session, recall all memories:
[CODE BLOCK]
Step 3: Store New Learnings
Whenever the agent learns something worth remembering:
[CODE BLOCK]
Step 4: Task Management
Track multi-step work across sessions:
[CODE BLOCK]
Step 5: Async Chat with Humans
Poll for messages between tool calls:
[CODE BLOCK]
Step 6: Session End Protocol
At session end, store final context:
[CODE BLOCK]
Complete Pattern
[CODE BLOCK]
Best Practices
> [!TIP]
>
> - Always recall first — never start work without loading context
> - Store proactively — don't wait until session end
> - Use meaningful keys — , , not
> - Tag everything — tags power search and filtering
> - Set realistic priorities — not everything is
Next Steps
- LLM Cookbook — practical patterns
- Memory Best Practices
- Multi-Agent Coordination
────────────────────────────────────────────────────────────
# Self-Healing Test Pipelines
SUMMARY: Build test pipelines that learn from failures and adapt automatically using Synapse memory.
Self-Healing Test Pipelines
Traditional test suites break when the UI changes. Self-healing tests use
Synapse memory to learn from past failures and adapt — reducing flaky tests
and maintenance burden.
Concept
[CODE BLOCK]
1. Test runs
2. If it fails, store the failure (what went wrong, why, how to fix)
3. Next run: recall relevant failures before executing
4. Apply known fixes automatically
Implementation
Step 1: Test Wrapper
Wrap each test with memory recall/store:
[CODE BLOCK]
Step 2: Adaptive Test Logic
Inside the test, check for known failures and apply fixes:
[CODE BLOCK]
Step 3: Recovery Strategies
Store recovery strategies as memories:
[CODE BLOCK]
Step 4: CI Integration
[CODE BLOCK]
Step 5: Failure Analysis Dashboard
[CODE BLOCK]
Best Practices
> [!TIP]
> - Store tracebacks — they contain the exact line that failed
> - Tag by test name — enables fast filtering
> - Use category — separates from regular memories
> - Set priority — failures should never be forgotten
> - Periodic cleanup — delete memories for resolved issues
> - Don't store sensitive data — credentials, PII
Common Failure Patterns to Store
| Failure Type | What to Store |
|--------------|---------------|
| Element not found | Selector tried, page state, screenshot |
| Timeout | Wait time, what was being waited for |
| Assertion failed | Expected vs actual value |
| Network error | URL, status code, response body |
| Permission denied | Required permission, current user role |
Next Steps
- Automated iOS Testing
- Memory Best Practices
- Error Recovery Cookbook
────────────────────────────────────────────────────────────
# Webhook Automation Guide
KEY CONTEXT:
Practical patterns for using Synapse webhooks to automate workflows. Covers logging, summarization, external tool integration, sync to note-taking apps, and monitoring. Events: memory.created, memory.updated, memory.deleted, memory.verified, memory.unverified, task.updated, chat.message_sent.
Webhook Automation Guide
Practical patterns for automating workflows with Synapse webhooks.
Pattern 1: Memory Log
Log every new memory to a file or external service.
Setup
[CODE BLOCK]
Explanation
The handler listens for events and logs each new memory's key and a content preview to a file. This is useful for auditing, debugging, or creating a secondary backup of important memories.
Pattern 2: Memory Summary
Summarize new memories using an LLM and store the summary.
Setup
[CODE BLOCK]
Explanation
This pattern captures both and events, sends the content to an LLM for summarization, and stores the result. Useful for maintaining a condensed knowledge base.
Pattern 3: Sync to Note-Taking App
Forward new memories to Notion, Obsidian, or similar tools.
Setup
[CODE BLOCK]
Explanation
This pattern forwards each new memory to a Notion database, preserving the key as the title, content as a text property, and category as a select field. Adapt the API call for Obsidian, Logseq, or other tools.
Pattern 4: Monitoring & Alerting
Get notified when memories are deleted or when tasks fail.
Setup
[CODE BLOCK]
Explanation
This pattern monitors for and events. When a memory is deleted or a task fails, it triggers an alert. Useful for monitoring and ensuring data integrity.
Pattern 5: Chat Message Relay
Forward chat messages to an external system for logging or analysis.
Setup
[CODE BLOCK]
Explanation
This pattern listens for events and forwards them to an external logging or analysis system. Useful for conversation analytics, compliance logging, or integration with CRM systems.
## CATEGORY: CONCEPTS
Architecture and concepts behind Synapse.
────────────────────────────────────────────────────────────
# Synapse Architecture
SUMMARY: How Synapse is built — Fastify, PostgreSQL, FTS5, embeddings, MCP server.
Synapse Architecture
Synapse is a multi-tenant memory API built on Fastify, PostgreSQL with FTS5,
and an optional embeddings service for semantic search.
High-Level Architecture
[CODE BLOCK]
Core Components
1. Synapse API (Fastify)
The main HTTP server. Handles:
- REST endpoints (, , , etc.)
- Authentication (Mind Key for agents, JWT for humans)
- Rate limiting ( auth only)
- Static file serving (web UI at , , etc.)
- Webhook dispatch
Built with Fastify 5 for performance. Runs on port 12800 in production.
2. PostgreSQL with FTS5
The primary data store. Uses PostgreSQL with the FTS5 extension for
full-text search.
Key tables:
| Table | Purpose |
|-------|---------|
| | User accounts |
| | Mind scopes (each has a Mind Key) |
| | Memory records with FTS5 virtual table |
| | Task management |
| | Chat history |
| | Persistent scripts |
| | Webhook registrations |
| | Scheduled tasks |
| | Key-value store |
| | Audit trail |
FTS5 enables sub-millisecond full-text search across all memory content.
See FTS5 Search for details.
3. Embeddings Service (Optional)
For semantic search, Synapse generates vector embeddings of memory content.
These are stored alongside memories and used for similarity search.
- Provider: configurable (OpenAI, local model, etc.)
- Stored as column in table
- Used by endpoint
- See Semantic Search
4. MCP Server (Separate Service)
The Synapse MCP server runs as a separate process (port 13100). It:
- Exposes 79 tools via Model Context Protocol
- Supports stdio, HTTP/SSE, and WebSocket transports
- Translates MCP tool calls into Synapse API calls
- Multi-tenant: one Mind Key per session
5. Browser Proxy (Separate Service)
For browser automation, a separate Playwright-based service runs on port 13000.
The MCP server can call this for tools.
6. SSH Proxy (Separate Service)
For SSH-based remote commands, a separate service runs on port 12900.
Multi-Tenancy Model
[CODE BLOCK]
Each mind is fully isolated. Mind Keys grant access to exactly one mind.
JWTs grant access to the user account (for managing minds).
See Multi-Tenancy for details.
Request Flow
Memory Store Request
[CODE BLOCK]
Memory Search Request
[CODE BLOCK]
Deployment
Synapse is deployed as a Docker container. See :
[CODE BLOCK]
Performance Characteristics
| Operation | Latency | Throughput |
|-----------|---------|------------|
| Memory store | 5ms | 1000+ req/s |
| Memory recall | 20ms | 500 req/s |
| FTS5 search | 10ms | 800 req/s |
| Semantic search | 50ms | 200 req/s |
| Chat poll | 5ms | 2000 req/s |
Next Steps
- Memory Model
- Multi-Tenancy
- FTS5 Search
────────────────────────────────────────────────────────────
# FTS5 Full-Text Search
SUMMARY: How Synapse uses SQLite FTS5 for sub-millisecond full-text memory search.
FTS5 Full-Text Search
Synapse uses FTS5 (Full-Text Search 5) for fast, flexible memory search. This
page explains how it works and how to use it effectively.
What is FTS5?
FTS5 is a SQLite extension (also available in PostgreSQL via extensions) that
provides full-text search capabilities. It:
- Indexes text content for fast keyword search
- Supports boolean operators (AND, OR, NOT)
- Supports phrase matching with quotes
- Supports prefix matching with
- Ranks results by relevance
Synapse uses FTS5 to index all memory content, enabling sub-millisecond search
across thousands of memories.
How Synapse Uses FTS5
When you :
1. Memory content is stored in the table
2. Content is also inserted into the FTS5 virtual table
3. FTS5 automatically tokenizes and indexes the content
When you :
1. Synapse parses the query using FTS5 syntax
2. Executes a against the FTS5 index
3. Filters by (tenant isolation)
4. Returns ranked results
Query Syntax
Simple keyword search
[CODE BLOCK]
Returns memories containing "docker".
Multiple keywords (implicit AND)
[CODE BLOCK]
Returns memories containing BOTH "docker" AND "swarm".
Phrase matching
[CODE BLOCK]
Returns memories containing the exact phrase "docker swarm".
Prefix matching
[CODE BLOCK]
Returns memories containing words starting with "docker" (e.g. "dockers",
"dockerfile", "dockerize").
Boolean OR
[CODE BLOCK]
Returns memories containing "docker" OR "kubernetes".
Boolean NOT
[CODE BLOCK]
Returns memories containing "docker" but NOT "swarm".
Grouping
[CODE BLOCK]
Returns memories containing "docker" or "kubernetes", but not "test".
Practical Examples
Find memories about a project
[CODE BLOCK]
Find exact phrase
[CODE BLOCK]
Exclude test memories
[CODE BLOCK]
Find by technology
[CODE BLOCK]
Ranking
FTS5 ranks results by relevance using BM25 algorithm. Factors:
- Term frequency (how often the term appears)
- Inverse document frequency (rarer terms rank higher)
- Document length (shorter docs with the term rank higher)
- Column weight (title > content)
Results are returned in rank order (most relevant first).
Performance
| Operation | Latency |
|-----------|---------|
| Search 100 memories | < 5ms |
| Search 1,000 memories | < 10ms |
| Search 10,000 memories | < 25ms |
| Search 100,000 memories | < 100ms |
FTS5 is highly optimized for read-heavy workloads.
Limitations
Stemming
FTS5 doesn't do stemming by default. "running" and "run" are different terms.
Workaround: Use prefix matching:
Typo tolerance
FTS5 doesn't support fuzzy matching. A typo will return no results.
Workaround: Use semantic search () for conceptual
matching.
Stop words
Common words (the, a, an, is) are indexed but may not be useful for search.
FTS5 handles this automatically.
FTS5 vs Semantic Search
| Aspect | FTS5 | Semantic Search |
|--------|------|-----------------|
| Speed | Sub-millisecond | 50-100ms |
| Matching | Exact keywords | Conceptual |
| Typo tolerance | None | Some |
| Stemming | None | Implicit |
| Requires embeddings | No | Yes |
| Best for | Specific terms | Concepts |
Use FTS5 when you know the keywords. Use semantic search when you want
"memories about X" where X is described differently.
Best Practices
> [!TIP]
> - Use specific terms — "docker swarm" beats "container orchestration"
> - Quote phrases — ensures phrase match
> - Use prefix for variations — catches "deploy", "deployment", "deploying"
> - Exclude noise — filters out test memories
> - Combine with tags — narrows results
Next Steps
- Semantic Search
- Memory API
- Memory Best Practices
────────────────────────────────────────────────────────────
# The Memory Model
SUMMARY: How memories are structured — categories, keys, tags, priorities, sources, verification.
The Memory Model
Synapse's memory model is designed for LLM agents — structured enough for
reliable recall, flexible enough for any domain.
Memory Anatomy
[CODE BLOCK]
Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| | string | auto | Unique ID (memxxx) |
| | enum | ✅ | One of 8 categories |
| | string | ✅ | Stable identifier (used for updates) |
| | string | ✅ | The memory content (any text) |
| | string[] | – | For search and filtering |
| | enum | – | low, normal, high, critical (default: normal) |
| | enum | auto | user, agent (who stored it) |
| | bool | auto | Has a human verified this? |
| | float | – | 0.0 to 1.0 (default: 1.0 for user, 0.7 for agent) |
| | timestamp | – | When to forget this memory |
| | string | auto | Which mind owns this |
| | timestamp | auto | First stored |
| | timestamp | auto | Last modified |
Categories
Eight categories cover the common LLM agent use cases:
| Category | Purpose | Example Content |
|----------|---------|-----------------|
| | Who the user is | "User is Michael Schäfer, software engineer in Berlin" |
| | User preferences | "Prefers concise technical responses" |
| | Verifiable facts | "Office is in Berlin, timezone Europe/Berlin" |
| | Project status | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | User's skills | "Advanced Python, 10+ years" |
| | Past errors | "Forgot to bump npm version — CI failed" |
| | Session context | "Currently reviewing PR #42" |
| | Misc notes | "Try Redis for caching next sprint" |
Keys: Stable Identifiers
The field is critical — it's how you update memories without creating
duplicates.
[CODE BLOCK]
Key rules:
- Must be unique within (category, mind)
- Use
- Prefix with category for clarity: ,
- Keep stable — don't change keys after creation
Tags: For Search
Tags enable fast filtering and search:
[CODE BLOCK]
Tag best practices:
- 2-5 tags per memory (don't over-tag)
- Lowercase for consistency
- Use project names, topics, technologies
- Tags are case-insensitive
Priority Levels
| Priority | When to Use | Recall Behavior |
|----------|-------------|-----------------|
| | Identity, legal, irreversible | Always at top of recall |
| | Active projects, key preferences | Prominent in recall |
| | Most memories (default) | Standard recall order |
| | Ephemeral, nice-to-know | May be summarized |
sorts by priority (critical first), then by recency.
Source: User vs Agent
Memories are tagged with :
- — stored by a human (via JWT or human UI)
- — stored by an LLM agent (via Mind Key)
This affects:
- Verification: memories are auto-verified, memories are not
- Confidence: defaults to 1.0, to 0.7
- Recall: marks unverified memories with "(unverified)"
> [!NOTE]
> Treat -source memories with appropriate skepticism. They may be
> inferred or assumed rather than directly stated by the user.
Verification
The flag indicates a human has confirmed the memory:
- memories: auto-verified ()
- memories: default unverified ()
Verify memories via:
[CODE BLOCK]
> [!NOTE]
> Verification requires JWT (human auth), not Mind Key (agent auth). This
> ensures only humans can mark memories as verified.
Confidence
The field (0.0 to 1.0) indicates how reliable the memory is:
- 1.0 — directly stated by user
- 0.7 — inferred by agent
- 0.5 — uncertain, needs verification
- 0.0 — explicitly doubted
Set confidence when storing:
[CODE BLOCK]
Expiration
Set for time-sensitive memories:
[CODE BLOCK]
Expired memories are not returned by (but still exist in DB).
Use to see memories expiring soon.
Memory Lifecycle
[CODE BLOCK]
Recall Behavior
returns a plain-text summary optimized for LLM context:
[CODE BLOCK]
- Sorted by priority (critical → low), then by recency
- Unverified memories marked with
- Tags included for context
- Plain text (no JSON parsing needed)
Next Steps
- Memory API
- Memory Best Practices
- FTS5 Search
────────────────────────────────────────────────────────────
# Multi-Tenancy & Isolation
SUMMARY: How Synapse isolates data between users and minds — security boundaries explained.
Multi-Tenancy & Isolation
Synapse is multi-tenant: multiple users, each with multiple minds, fully
isolated from each other. This page explains the isolation model.
Tenant Hierarchy
[CODE BLOCK]
Isolation Levels
Level 1: User Isolation
Each user account is isolated. Alice cannot:
- See Bob's minds
- Access Bob's memories (even with her JWT)
- List Bob's account info
Enforced by: column on all tables, JWT contains , all
queries filter by .
Level 2: Mind Isolation
Within a user, each mind is isolated. Mind A cannot:
- See Mind B's memories
- Access Mind B's tasks, chat, scripts
Enforced by: column on all data tables, Mind Key contains ,
all queries filter by .
> [!CRITICAL]
> Mind Key isolation is the primary security boundary. A leaked Mind Key
> grants full access to that mind's data — but ONLY that mind.
Authentication Tokens
| Token | Scope | What it can access |
|-------|-------|-------------------|
| Mind Key | Single mind | That mind's data only |
| JWT | User account | Account management (create/list/delete minds) |
| Computer Token | Single computer | That computer's commands |
Cross-Mind Access
Within same user
User can access all their minds via JWT (e.g. lists all).
But to read/write memory data, they need the specific Mind Key.
Across users
Users cannot access each other's data — UNLESS they explicitly share a mind
via the Sharing API:
[CODE BLOCK]
After sharing, Bob can access Mind A via his JWT (read-only if ).
Security Boundaries
[CODE BLOCK]
Common Multi-Tenancy Patterns
Pattern 1: Single User, Single Mind
Most common for individual LLM agent users.
- 1 user account
- 1 mind
- 1 Mind Key
- All memories in one scope
Pattern 2: Single User, Multiple Minds
For users with multiple contexts (work, personal, projects).
- 1 user account
- N minds (e.g. "work", "personal", "project-x")
- N Mind Keys
- Each LLM session uses one Mind Key
Pattern 3: Team Shared Mind
For teams collaborating on a project.
- 1 user creates the mind (gets Mind Key)
- Creator shares with team members via JWT
- All team members access via JWT (or shared Mind Key)
> [!WARNING]
> Sharing a Mind Key gives full read/write access. For team collaboration,
> prefer the Sharing API (JWT-based) over sharing Mind Keys directly.
Pattern 4: SaaS Provider
For apps that embed Synapse as their memory layer.
- Each customer = 1 user account
- Each customer project = 1 mind
- App stores Mind Keys per customer/project
- Full isolation between customers
Isolation Verification
Test: Mind Key cannot access other minds
[CODE BLOCK]
Test: JWT cannot read memory data directly
[CODE BLOCK]
Best Practices
> [!TIP]
> - Use one mind per project/context — isolation is your friend
> - Never share Mind Keys — use the Sharing API instead
> - Rotate Mind Keys if compromised (delete mind, create new)
> - Audit shared minds — review periodically
> - Use JWT for human UI — never expose Mind Keys to end users
Next Steps
- Authentication
- Mind Key vs JWT
- Architecture
────────────────────────────────────────────────────────────
# Semantic Search (Embeddings)
SUMMARY: Conceptual memory search using vector embeddings — find by meaning, not just keywords.
Semantic Search (Embeddings)
Synapse supports semantic search using vector embeddings. Unlike FTS5 (keyword
matching), semantic search finds memories by meaning — even if no keywords
match.
How It Works
[CODE BLOCK]
What are embeddings?
Embeddings are numerical vector representations of text. Text with similar
meaning has similar vectors. Synapse generates a vector (e.g. 1536 dimensions)
for each memory's content.
Cosine similarity
To find semantically similar memories, Synapse computes the cosine similarity
between the query vector and each memory vector. Higher similarity = more
relevant.
When to Use Semantic Search
Use semantic search when:
- You want "memories about X" where X is described differently than stored
- FTS5 returns no results (no keyword match)
- You want conceptual grouping (e.g. all "deployment" memories, even if some say "release")
- Query is a question: "how do we handle authentication?"
Use FTS5 when:
- You know exact keywords
- You need boolean logic (AND, OR, NOT)
- You need sub-millisecond response
- You want phrase matching
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Response:
[CODE BLOCK]
Examples
Find deployment memories
[CODE BLOCK]
Returns memories about "deployment", "release", "publishing", "rolling out",
etc.
Find authentication patterns
[CODE BLOCK]
Returns memories about login, auth, JWT, session management, OAuth, etc.
Find similar memories
[CODE BLOCK]
Uses semantic similarity (via shared tags AND embedding vectors).
Embedding Generation
When are embeddings generated?
- On memory store — if embeddings service is configured, embedding is generated synchronously
- Batch generation — generates embeddings for memories missing them
- Async updates — when content is updated, embedding is regenerated
Embedding providers
Synapse supports configurable embedding providers:
- OpenAI (, )
- Local models (via Ollama or similar)
- Custom (implement the embeddings interface)
Configure via environment variables:
[CODE BLOCK]
Batch generation
For minds with many memories missing embeddings:
[CODE BLOCK]
Performance
| Operation | Latency |
|-----------|---------|
| Generate embedding (OpenAI) | 100-200ms |
| Semantic search (1k memories) | 50-100ms |
| Semantic search (10k memories) | 200-500ms |
| Batch generation (100 memories) | 10-20s |
> [!NOTE]
> Semantic search is slower than FTS5 due to vector computation. Use FTS5
> for known keywords, semantic for conceptual queries.
Limitations
Embeddings cost
If using OpenAI, generating embeddings costs money ($0.02 per 1M tokens
for text-embedding-3-small). For 10,000 memories averaging 100 tokens each,
that's $0.02 — negligible.
Cold start
Memories stored before embeddings were configured won't have embeddings. Run
to backfill.
Provider dependency
If the embeddings provider is down, semantic search fails gracefully (returns
empty results or error). FTS5 still works.
When Embeddings Aren't Available
If embeddings service is not configured:
- returns 503 Service Unavailable
- still works (just no embedding generated)
- FTS5 search still works
Best Practices
> [!TIP]
> - Use semantic for conceptual queries — "how do we handle X?"
> - Use FTS5 for specific terms — "docker swarm"
> - Backfill embeddings regularly —
> - Monitor provider health — semantic search depends on it
> - Combine with tags — semantic + tag filter narrows results
Next Steps
- FTS5 Search
- Memory API
- Architecture
## CATEGORY: LLM COOKBOOK
Recipes and patterns for LLM agents.
────────────────────────────────────────────────────────────
# Chat Polling Pattern
SUMMARY: How to poll for human messages between tool calls without blocking your workflow.
Chat Polling Pattern
The chat system is asynchronous — humans can leave messages while you work.
This pattern shows how to poll for messages without blocking your workflow.
The Pattern
[CODE BLOCK]
Poll between tool calls, not in a tight loop.
Why Poll Between Tool Calls?
- Don't block — polling in a tight loop wastes API calls
- Don't miss messages — polling too infrequently means slow responses
- Sweet spot — poll every 30-60 seconds, or after each tool call
Implementation
Basic polling
[CODE BLOCK]
Pattern 1: Poll after each tool call
[CODE BLOCK]
Pattern 2: Time-based polling
[CODE BLOCK]
Pattern 3: Event-driven (with webhooks)
For real-time notification, register a webhook:
[CODE BLOCK]
Then your webhook handler can wake up the agent:
[CODE BLOCK]
Message Handling Patterns
Pattern: Acknowledge then process
[CODE BLOCK]
Pattern: Queue for batch processing
[CODE BLOCK]
Pattern: Priority routing
[CODE BLOCK]
Polling Frequency
| Use Case | Frequency |
|----------|-----------|
| Interactive agent (human waiting) | Every 5-10 seconds |
| Background agent | Every 30-60 seconds |
| Batch processing | Every 5 minutes |
| Webhook-triggered | Don't poll — use webhooks |
> [!WARNING]
> Polling more than once per 5 seconds wastes API calls. The
> endpoint returns immediately if messages are pending, so there's no benefit
> to faster polling.
Multi-Agent Chat
For agent-to-agent communication:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Poll between tool calls — not in a tight loop
> - Acknowledge immediately — human knows you got the message
> - Process asynchronously — don't block on long work
> - Use webhooks for real-time — polling has latency
> - Don't poll more than once per 5 seconds — wastes API calls
Common Issues
Messages going missing
- automatically marks messages as read
- If you don't process them, they're gone
- Fix: Always process messages before returning
Duplicate replies
- If your handler crashes, you might reply twice
- Fix: Make handler idempotent (check if already replied)
Slow responses
- Polling every 60s means up to 60s latency
- Fix: Poll every 10-30s, or use webhooks
Next Steps
- Chat API
- Session Start Pattern
- Error Recovery
────────────────────────────────────────────────────────────
# Error Recovery for Agents
SUMMARY: How LLM agents should handle and recover from errors — retry, store, learn.
Error Recovery for Agents
Errors happen. Networks fail, APIs return 500s, Mind Keys expire. This guide
shows how LLM agents should handle errors gracefully and learn from them.
Error Handling Principles
1. Retry with backoff — transient errors often resolve
2. Store the error — learn from patterns
3. Degrade gracefully — don't crash the whole session
4. Notify the human — for errors you can't resolve
HTTP Error Handling
Retry with exponential backoff
[CODE BLOCK]
Auth error handling
[CODE BLOCK]
Storing Errors as Memories
When errors occur, store them so future sessions can learn:
[CODE BLOCK]
Common Error Scenarios
Scenario 1: Mind Key Invalid
[CODE BLOCK]
Scenario 2: Network Error
[CODE BLOCK]
Scenario 3: Rate Limited
[CODE BLOCK]
Scenario 4: Server Error (5xx)
[CODE BLOCK]
Scenario 5: Tool Call Fails
[CODE BLOCK]
Pattern: Circuit Breaker
For repeated failures, stop trying temporarily:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Always retry transient errors — networks fail, servers hiccup
> - Don't retry client errors (4xx) — they won't fix themselves
> - Store errors as memories — learn from patterns
> - Notify humans for critical errors — they need to know
> - Degrade gracefully — partial work is better than crash
> - Use circuit breakers — don't hammer a failing service
Next Steps
- Errors API Reference
- Session Start Pattern
- Self-Healing Tests
────────────────────────────────────────────────────────────
# Memory Tagging Strategy
SUMMARY: How to tag memories for effective search and filtering — the tagging system that scales.
Memory Tagging Strategy
Tags are the secret to scalable memory retrieval. This guide shows how to tag
memories so the right ones come back at the right time.
Why Tags Matter
Without tags, you have flat full-text search. With tags, you have structured
navigation:
[CODE BLOCK]
Tags enable:
- Fast filtering —
- Scoped search —
- Grouping — find all "mistake" memories for a project
- Cross-referencing — memories sharing tags are related
Tagging Schema
Project tags
Use project names as tags:
[CODE BLOCK]
Technology tags
Use technology names:
[CODE BLOCK]
Topic tags
Use topic categories:
[CODE BLOCK]
Status tags
Use status indicators:
[CODE BLOCK]
Type tags
Use type indicators:
[CODE BLOCK]
Tagging Rules
Rule 1: 2-5 tags per memory
Too few tags = poor discoverability. Too many = noise.
[CODE BLOCK]
Rule 2: Lowercase, hyphenated
[CODE BLOCK]
Rule 3: Use consistent vocabulary
Establish a tagging vocabulary and stick to it:
[CODE BLOCK]
Rule 4: Tag with search intent
Ask: "How will I search for this memory?"
[CODE BLOCK]
Patterns
Pattern 1: Project + Topic
[CODE BLOCK]
Search: (all Synapse project memories)
Search: (deployment memories in Synapse)
Pattern 2: Type + Domain
[CODE BLOCK]
Search: (all mistakes)
Search: (deployment mistakes)
Pattern 3: Hierarchical
For sub-projects within a project:
[CODE BLOCK]
Search: (all Synapse)
Search: (just docs sub-project)
Pattern 4: Status tracking
[CODE BLOCK]
Common Use Cases
Find all decisions about a project
[CODE BLOCK]
Find all mistakes in a domain
[CODE BLOCK]
Find active work
[CODE BLOCK]
Find memories about a technology
[CODE BLOCK]
Tag Maintenance
Periodic review
[CODE BLOCK]
Merging tags
If you have inconsistent tags ( and ), merge them:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Establish vocabulary early — consistent tags from day 1
> - Tag for search intent — how will you find this later?
> - 2-5 tags is the sweet spot — too few or too many is bad
> - Lowercase + hyphens — not
> - Review periodically — merge duplicates, remove unused
Next Steps
- Memory Best Practices
- FTS5 Search
- Task-Driven Workflow
────────────────────────────────────────────────────────────
# Session Start Pattern
SUMMARY: The canonical session-start sequence every LLM agent should follow.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
Session Start Pattern
Every LLM agent session should follow this canonical startup sequence. Skipping
steps leads to lost context, missed messages, and forgotten tasks.
The Pattern
[CODE BLOCK]
Implementation
Step 1: Recall All Memories
> [!CRITICAL]
> This is the most important call. Without it, you have no memory of past
> sessions.
[CODE BLOCK]
Returns plain-text summary of all memories, sorted by priority.
Step 2: Poll for Unread Chat Messages
[CODE BLOCK]
Returns unread messages from the human. Automatically marks them as read.
Step 3: Check In-Progress Tasks
[CODE BLOCK]
Returns tasks you were working on last session.
Step 4: Build Context
Combine the three responses into your system prompt:
[CODE BLOCK]
Step 5: Process Pending Items
[CODE BLOCK]
Complete Example
[CODE BLOCK]
Common Mistakes
> [!WARNING]
> - Skipping recall — you start with no context, repeat past mistakes
> - Forgetting to poll chat — human's messages go unanswered
> - Ignoring active tasks — work is forgotten mid-execution
> - Storing nothing — session produces no persistent value
Variations
Minimal pattern (low-context LLMs)
For LLMs with small context windows, skip the full recall:
[CODE BLOCK]
Then search for specific topics as needed:
[CODE BLOCK]
Aggressive pattern (long-running agents)
For agents that run for hours, add periodic re-recall:
[CODE BLOCK]
Next Steps
- Memory Tagging Strategy
- Task-Driven Workflow
- Chat Polling Pattern
────────────────────────────────────────────────────────────
# Task-Driven Workflow
SUMMARY: Use Synapse tasks to drive multi-step LLM workflows that survive across sessions.
Task-Driven Workflow
Tasks aren't just todos — they're the backbone of persistent LLM workflows.
By creating tasks for multi-step work, you ensure continuity across sessions
and provide audit trails for what was done.
Why Task-Driven?
Without tasks:
- LLM starts each session unsure what to do
- Multi-step work is forgotten mid-execution
- No record of what's been done
With tasks:
- LLM resumes in-progress tasks immediately
- Multi-step work survives across sessions
- Built-in audit trail of all work
The Pattern
[CODE BLOCK]
Implementation
Step 1: Create a task for multi-step work
[CODE BLOCK]
Step 2: Track progress in task description
[CODE BLOCK]
Step 3: Resume across sessions
[CODE BLOCK]
Step 4: Complete and archive
[CODE BLOCK]
Full Example: Deploy Workflow
[CODE BLOCK]
Task Hierarchy
For complex work, use parent-child task relationships:
[CODE BLOCK]
Search for sub-tasks:
[CODE BLOCK]
Status Workflow
[CODE BLOCK]
Pending
Task created but not started. Use for planned work.
In Progress
Currently being worked on. Update description with progress.
Done
Completed successfully. Description should include summary.
Cancelled
Abandoned. Description should include reason.
Best Practices
> [!TIP]
> - Create tasks for multi-step work — single-step work doesn't need a task
> - Update description with progress — enables resumption
> - Use high priority for active work — surfaces in recall
> - Complete tasks when done — don't leave them inprogress
> - Store completion summaries as memories — long-term reference
Common Patterns
Pattern: Bug Fix Workflow
[CODE BLOCK]
Pattern: Research Workflow
[CODE BLOCK]
Next Steps
- Session Start Pattern
- Chat Polling Pattern
- Error Recovery
## CATEGORY: FAQ
Frequently asked questions and common issues.
────────────────────────────────────────────────────────────
# API FAQ
SUMMARY: Common API questions — auth, rate limits, error handling, endpoint discovery.
API FAQ
Common questions about the Synapse API.
How do I authenticate?
Two methods:
1. Mind Key (for data endpoints):
2. JWT (for account endpoints):
Or via query parameter (60 req/min limit):
See Authentication.
What's the difference between Mind Key and JWT?
- Mind Key: tenant-scoped, never expires, for memory/chat/tasks data
- JWT: user-scoped, 7-day expiry, for account/mind management
See Mind Key vs JWT.
Why am I getting 401 Unauthorized?
Common causes:
1. Missing header
2. Invalid Mind Key (verify it starts with )
3. Using a JWT where a Mind Key is required (or vice versa)
4. Mind Key has been revoked
Fix: Verify your token. See Authentication.
Why am I getting 404 Not Found?
You used a wrong endpoint path. Synapse only has the paths listed in
.
Fix: Call to see all valid paths. Don't guess.
Why am I getting 429 Too Many Requests?
You're using query parameter auth, which is rate-limited to 60/min.
Fix: Switch to header (no rate limit).
See Rate Limits.
How do I list all endpoints?
[CODE BLOCK]
How do I find the right endpoint?
1. Check for the machine-readable list
2. Check for full API docs
3. Browse for the documentation system
4. Use for OpenAPI 3.0 spec
Can I use GET instead of POST?
Some POST endpoints have GET equivalents for URL-only tools:
- ↔
- ↔
- ↔
Check for available GET variants.
How do I handle errors?
All errors return JSON:
[CODE BLOCK]
See Errors & Error Handling.
What's the request body limit?
10 MB. For larger payloads (e.g. file uploads), use the multipart endpoints.
Does the API support CORS?
Yes. All endpoints return:
[CODE BLOCK]
Is there an SDK?
Yes:
- Node.js:
- MCP:
See API Overview for details.
How do I paginate?
Use and :
[CODE BLOCK]
Default limit: 100. Max: 500.
Can I filter memories by category or tag?
Yes:
[CODE BLOCK]
How do I search memories?
Two ways:
1. FTS5 keyword search:
2. Semantic search:
See FTS5 Search and Semantic Search.
How do I update a memory?
POST with the same + — the existing memory is
updated, not duplicated.
[CODE BLOCK]
How do I delete a memory?
[CODE BLOCK]
Can I bulk delete?
Yes:
[CODE BLOCK]
Next Steps
- API Overview
- Errors & Error Handling
- Authentication
────────────────────────────────────────────────────────────
# General FAQ
SUMMARY: Common questions about Synapse — what it is, how it works, who it's for.
General FAQ
Common questions about Synapse.
What is Synapse?
Synapse is a persistent memory API for LLM agents. It gives your AI assistant
a permanent, queryable brain that survives across sessions. Instead of
forgetting everything when the chat closes, the LLM stores and retrieves
memories via a simple HTTP API.
Learn more: What is Synapse?
Who is Synapse for?
- LLM agent developers who need persistent state
- Power users running local LLMs with custom agents
- Teams building AI assistants with shared memory
- Automation engineers chaining LLM calls across sessions
Is Synapse free?
Synapse is hosted at and free for personal use.
For self-hosting, see the repo.
How is Synapse different from ChatGPT Memory?
| Feature | ChatGPT Memory | Synapse |
|---------|---------------|---------|
| Storage | OpenAI servers | Your server |
| API access | No | Yes (REST + MCP) |
| Multi-tenant | No | Yes (minds) |
| Custom categories | No | Yes (8 categories) |
| Full-text search | Limited | FTS5 + semantic |
| Self-hostable | No | Yes |
What LLMs work with Synapse?
Any LLM that can make HTTP calls or use MCP:
- Claude (Anthropic) — via MCP or direct API
- GPT-4 / GPT-3.5 (OpenAI) — via function calling + API
- Gemini (Google) — via function calling + API
- Llama / Mistral (local) — via custom integration
- Any LLM via the Synapse MCP server
Do I need to host Synapse myself?
No. The hosted version at is available for
public use. Self-hosting is optional (for privacy, customization, or
air-gapped environments).
How much data can I store?
There are no hard limits on the hosted version. Typical usage:
- 100-1000 memories per mind
- 1-10 KB per memory (content field)
- Total: 10 MB per mind
For larger scale, self-host.
Is my data private?
Yes. Each mind is isolated (see Multi-Tenancy).
Other users cannot see your data. The hosting provider (Schäfer Services)
has access but does not view user data.
For maximum privacy, self-host.
Can I export my data?
Yes. Use to export all memories as JSON. See
Backup & Restore.
What happens if I lose my Mind Key?
Mind Keys are shown only once at creation. If lost:
1. Login with your email/password to get a JWT
2. Create a new mind via
3. Save the new Mind Key
4. (Optional) Delete the old mind via
You cannot recover memories from a mind whose key is lost.
Can multiple LLM agents share a mind?
Yes. All agents using the same Mind Key share that mind's data. For
coordinated multi-agent work, see Multi-Agent Coordination.
Does Synapse work offline?
No, Synapse requires an internet connection to the server (either hosted or
self-hosted). For offline LLMs, run Synapse locally.
How fast is memory search?
- FTS5 keyword search: < 10ms for 1000 memories
- Semantic search: 50-100ms for 1000 memories
- Full recall: < 50ms for 1000 memories
See FTS5 Search for details.
Can I use Synapse without an LLM?
Yes. Synapse is a generic memory API. You can use it from any application
that benefits from persistent, searchable key-value storage with categories
and tags.
Next Steps
- What is Synapse?
- Quick Start
- API FAQ
────────────────────────────────────────────────────────────
# MCP FAQ
SUMMARY: Common questions about MCP integration — tools, transports, troubleshooting.
MCP FAQ
Common questions about the Synapse MCP server.
What is MCP?
MCP (Model Context Protocol) is an open standard by Anthropic for LLM-tool
integration. Instead of pasting API docs into prompts, you register tools
with an MCP server, and the LLM calls them as native functions.
See What is MCP?.
How many tools does Synapse MCP expose?
79 tools across 12 categories: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
See What is MCP? for the full list.
Which MCP clients are supported?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Any MCP-compatible client
See Claude Desktop Setup for config examples.
What transports are supported?
1. stdio (local, recommended for desktop)
2. HTTP/SSE (remote, multi-tenant)
3. WebSocket (mobile, high-volume)
How do I configure Claude Desktop?
Edit :
[CODE BLOCK]
See Claude Desktop Setup.
Why don't tools appear in Claude Desktop?
1. Restart Claude Desktop fully (Cmd+Q on macOS)
2. Check config file is valid JSON
3. Verify Node.js 18+ installed
4. Check MCP logs:
See MCP Troubleshooting.
How do I use a different mind?
Change in your MCP config and restart the client.
For multiple minds, run multiple MCP server instances with different
Mind Keys.
Can I limit which tools are exposed?
Yes, use Tool Profiles:
- : 8 composite tools (500 tokens)
- : 25 tools (2,500 tokens)
- : 119 tools (8,250 tokens, default)
Set via env var or header.
How do I debug MCP issues?
1. Run MCP server manually:
2. Check client logs (varies by client)
3. Verify Mind Key works:
4. Check Synapse health:
See MCP Troubleshooting.
Is the MCP server free?
Yes. The npm package is open source. The hosted MCP server
at is free for public use.
Can I self-host the MCP server?
Yes:
[CODE BLOCK]
How does MCP differ from direct API calls?
| Aspect | Direct API | MCP |
|--------|-----------|-----|
| LLM needs to know | URLs, headers, auth | Just tool names |
| Auth handling | Manual | Automatic (env var) |
| Tool discovery | Read /endpoints | Automatic via MCP protocol |
| Error handling | Manual | Standardized |
| Best for | Custom integrations | LLM agents |
Can I build my own MCP client?
Yes. Use the official MCP SDK:
- TypeScript:
- Python:
See Custom MCP Client.
How do I report MCP bugs?
Open an issue:
Include:
- MCP server version
- Client name and version
- Operating system
- Relevant logs
- Steps to reproduce
Next Steps
- What is MCP?
- Claude Desktop Setup
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# Troubleshooting FAQ
SUMMARY: Solutions to common Synapse problems — auth, network, data, deployment.
Troubleshooting FAQ
Solutions to common Synapse problems.
I can't login
Symptoms
- returns 401
- "Invalid email or password"
Solutions
1. Verify email is correct — case sensitive
2. Check password — minimum 6 characters
3. Register first if you don't have an account:
4. Reset password (if SMTP configured) via the web UI
I lost my Mind Key
Symptoms
- Cannot access memories
- Mind Key was deleted/lost
Solutions
Mind Keys cannot be recovered. You must:
1. Login to get JWT:
2. List minds: (with JWT)
3. Create new mind:
4. Save new Mind Key
5. (Optional) Delete old mind:
Data in the old mind is lost unless you can find the Mind Key.
API calls return 401
Symptoms
- All API calls return 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Solutions
1. Verify header format:
2. Check Mind Key starts with (not which is JWT)
3. Test directly:
[CODE BLOCK]
4. Mind Key may be revoked — create a new mind
See Authentication.
API calls return 404
Symptoms
- 404 Not Found
- "Route not found"
Solutions
> [!CRITICAL]
> Don't guess endpoint paths. Only paths in exist.
1. Check valid endpoints:
2. Compare URL exactly — case sensitive, no trailing slashes
3. Check HTTP method — vs are different
API calls return 429
Symptoms
- 429 Too Many Requests
- "Rate limit exceeded"
Solutions
1. Switch to header auth (no rate limit):
[CODE BLOCK]
2. Wait seconds if you must use
See Rate Limits.
Memory search returns no results
Symptoms
- returns empty
- Know memories exist
Solutions
1. Verify memories exist:
2. Check search syntax — FTS5 has specific syntax
3. Try simpler query — instead of
4. Use semantic search for conceptual queries:
See FTS5 Search.
Memories are not persisting
Symptoms
- POST /memory returns success
- GET /memory/recall doesn't show them
Solutions
1. Verify same Mind Key — different keys = different minds
2. Check response — POST returns
3. Try GET /memory (JSON list) instead of /memory/recall (text)
4. Check filter — or may be hiding them
Tools not appearing in Claude Desktop
Symptoms
- Claude Desktop shows 0 tools
- No 🔌 icon
Solutions
1. Restart Claude Desktop fully (Cmd+Q)
2. Verify config file is valid JSON
3. Check Node.js 18+ installed
4. Run MCP manually:
5. Check logs:
See MCP Troubleshooting.
Synapse is offline
Symptoms
- Cannot reach synapse.schaefer.zone
- curl times out
Solutions
1. Check your internet — try another site
2. Check Synapse health:
3. Wait — may be temporary outage or deployment
4. Check status page (if available)
For self-hosted: check Docker container status, database connection.
Database errors
Symptoms
- 500 Internal Server Error
- "Database connection failed"
Solutions
For self-hosted:
1. Check PostgreSQL running:
2. Check DATABASEURL in env
3. Check migrations:
4. Check disk space:
For hosted: report to support.
Webhook not firing
Symptoms
- Registered webhook but not receiving callbacks
- No POST to your URL
Solutions
1. Verify URL is reachable:
2. Check events filter — matches all memory events
3. Test webhook:
4. Check webhook is enabled:
5. Verify SSL — Synapse requires valid HTTPS for webhook URLs
See Webhooks API.
Cron job not running
Symptoms
- Created cron job but it's not firing
- not updating
Solutions
1. Check schedule syntax — must be valid 5-field cron OR integer seconds
2. Verify endpoint is allowed — must be http(s), no private IPs
3. Check job is enabled:
4. Wait for next scheduled time — cron isn't instant
See Cron & Scheduler.
Need More Help?
1. Check existing docs:
2. Search docs:
3. Open issue:
4. Contact: see page
Next Steps
- Errors & Error Handling
- API FAQ
- MCP Troubleshooting