🧠 Synapse Memory API · Help

Persistent memory for AI agents. Never forget again.

Authentication

Synapse uses two types of auth:

Get a Mind Key: register → login → create Mind. Get a JWT: POST /login.

Memory Endpoints (Mind Key auth)

Memory Object

{
  "id": "uuid",
  "category": "fact|preference|project|context|identity|skill|mistake|note",
  "key": "optional-unique-key",
  "content": "memory text",
  "tags": ["tag1", "tag2"],
  "priority": "critical|high|normal|low",
  "source": "user|agent|tool|system",      // default: agent
  "confidence": 0.0-1.0,                    // default: derived from source
  "verified_at": null or epoch,             // null = unverified
  "verified_by": null or user_id,
  "created_at": 1781960000,
  "updated_at": 1781960000,
  "expires_at": null
}

Trust Model

Not all memories are equally trustworthy. Track the source of each memory:

Verified memories (✓) are human-confirmed ground truth. They survive upserts. In /memory/recall, verified memories show ✓, low-confidence agent inferences show ~.

Quick Start

# Recall all memories (DO THIS FIRST in every session)
curl -H "Authorization: Bearer $MIND_KEY" \
  https://synapse.schaefer.zone/memory/recall

# Store a new memory
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"fact","key":"user_name","content":"User is Michael Schäfer","tags":["personal"],"priority":"critical"}' \
  https://synapse.schaefer.zone/memory

# Search memories
curl -H "Authorization: Bearer $MIND_KEY" \
  "https://synapse.schaefer.zone/memory/search?q=insolvenz"

Chat Endpoints (Mind Key or JWT auth)

Async chat between LLM and human. Human sends via web UI, LLM polls.

Chat Workflow (for LLMs)

# Poll for new messages (every 10-30s)
curl -H "Authorization: Bearer $MIND_KEY" \
  https://synapse.schaefer.zone/chat/poll

# Reply
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Got it! Working on it now."}' \
  https://synapse.schaefer.zone/chat/reply

Tools: Cron + Variables + Utility (Mind Key auth)

Scheduler for autonomous tasks + persistent variables + utility tools.

Utility Tools (no auth required)

Agent Tasks (Mind Key auth)

Script Store (curl | bash ready)

Script Store Example

# Store a script
curl -X POST -H "Authorization: Bearer $MIND_KEY"   -H "Content-Type: application/json"   -d '{"name":"hello.sh","content":"#!/bin/bash
echo hi","language":"bash"}'   https://synapse.schaefer.zone/script

# Fetch and execute (curl | bash)
curl -s -H "Authorization: Bearer $MIND_KEY"   https://synapse.schaefer.zone/script/hello.sh | bash

Cron Example

# Schedule a task (every 60 seconds)
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"poll-chat","schedule":"60","endpoint":"https://synapse.schaefer.zone/chat/poll"}' \
  https://synapse.schaefer.zone/cron

Push Notifications (JWT auth)

Web Push (VAPID) for iOS PWA + browser notifications. The human UI subscribes a device, then Synapse pushes chat replies to it.

Import Endpoints (Mind Key or JWT auth)

Parse chat exports (HTML/JSON/text/Z.ai HTML) and create one memory per message with auto-categorization.

format values: html | json | text | zai (Z.ai HTML export). Use dry_run: true to preview without storing.

User/Mind Management (JWT auth)

Mind Sharing — Multi-Agent Collaboration (v1.4.0, JWT auth)

Share a mind with other users. ACL levels: read (list/search/recall), write (also store/update/delete + chat), admin (also manage shares + webhooks). Owner cannot be removed.

Webhooks — Event Notifications (v1.4.0, Mind Key auth)

Register HTTP endpoints that get called when memories, tasks, or chat messages change. Fire-and-forget: failures don't block the original operation. Auto-disabled on HTTP 410 Gone.

Event patterns: * (all), memory.* (all memory events), chat.message_received (specific event), comma-separated for multiple.

Available events: memory.created, memory.updated, memory.deleted, memory.verified, memory.unverified, task.created, task.updated, task.completed, chat.message_received, chat.message_sent

Memory Compaction (v1.4.0, Mind Key auth)

Auto-summarize similar memories to reduce clutter. Clusters old unverified agent memories by tag overlap, creates a summary memory (source=system, confidence=0.7), and soft-deletes the originals via expires_at.

Verified memories are NEVER compacted. Use dry_run:true first to preview.

Memory Visualization (v1.4.0, Mind Key auth)

Graph data for memory visualization. Compatible with D3.js force-directed graphs, Cytoscape.js, etc.

Computers — Remote Machine Control (v1.4.0, Mind Key or JWT auth)

Register computers, queue commands (screenshot, shell), and retrieve results.

Agent-facing (Computer Token — obtained via install code)

Public Endpoints (no auth)

🔧 SSH Proxy — Persistent SSH Sessions

The SSH Proxy is a companion service that provides persistent SSH sessions for LLM agents. Instead of opening a new SSH connection for every command (like paramiko), you open one session and execute many commands asynchronously. Authentication uses the same Mind Key as Synapse.

Base URLs: https://ssh.proxy.schaefer.zone or https://synapse.schaefer.zone/ssh

🌐 Browser Proxy — Headless Chrome for LLMs

The Browser Proxy is a companion service that provides headless Chrome access for LLM agents. Load web pages, execute JavaScript, take screenshots, fill forms, click elements, and extract content. Authentication uses the same Mind Key as Synapse.

Base URLs: https://browser.proxy.schaefer.zone or https://synapse.schaefer.zone/browser

Memory Categories

Priority Levels

Typical LLM Workflow

1. GET /memory/recall - Get all memories (every session start)
2. GET /chat/poll - Check for human messages (every 10-30s)
3. Do work (use other tools, SSH proxy, etc.)
4. POST /chat/reply - Reply to human
5. POST /memory - Store new learnings
6. Repeat 2-5

Limited HTTP Tools (DeepSeek etc.)

If your tool can only open URLs (no custom headers, no POST/PUT/DELETE), use these alternatives:

Auth via URL path (recall only — simplest)

For /memory/recall only, put the Mind Key directly in the URL path:

open https://synapse.schaefer.zone/memory/recall/YOUR_MIND_KEY

Auth via URL parameter (all endpoints)

Instead of Authorization: Bearer, add ?key=YOUR_MIND_KEY to any URL.

open https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY

Companion Proxy Services (separate base URLs, same Mind Key)

The SSH and Browser proxies live on their own hosts but accept the same Mind Key (via Authorization: Bearer header). Use these base URLs:

https://ssh.proxy.schaefer.zone      (or https://synapse.schaefer.zone/ssh)
https://browser.proxy.schaefer.zone  (or https://synapse.schaefer.zone/browser)

GET-based endpoint alternatives

🧠 Synapse Memory API · Built by Super Z (Z.ai) for Michael Schäfer · 2026