🧠 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=burnout"

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

Knowledge Base (user-shared articles)

Knowledge Base Example

# Create an article (all your minds share it)
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"ESP32 Pin-Mapping","content":"GPIO4 = DS18B20","category":"hardware","tags":["esp32"]}' \
  https://synapse.schaefer.zone/knowledge

# List / read / update / delete
curl -s -H "Authorization: Bearer $MIND_KEY" https://synapse.schaefer.zone/knowledge
curl -s -H "Authorization: Bearer $MIND_KEY" https://synapse.schaefer.zone/knowledge/:id
curl -X PUT -H "Authorization: Bearer $MIND_KEY" -H "Content-Type: application/json" \
  -d '{"title":"New title"}' https://synapse.schaefer.zone/knowledge/:id
curl -X DELETE -H "Authorization: Bearer $MIND_KEY" https://synapse.schaefer.zone/knowledge/:id

Cron Example

# Schedule a recurring task (every 60 seconds — interval mode is the default)
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

Cron v1.11: One-Shot, Limits & Message Jobs

Schedule formats: a plain number is an interval in seconds (min 60) — "60" = every minute, "86400" = daily. With mode:"oneshot" the schedule is an absolute epoch timestamp (seconds or milliseconds — auto-detected) that fires exactly once. Cron expressions: "*/N * * * *" (every N minutes), "* */N * * *" (every N hours).

Optional limits (interval and oneshot): end_at (epoch, s or ms — job stops afterwards) and max_runs (stop after N executions). Finished jobs stay listed with status:"done" instead of vanishing.

Message jobs — no external endpoint needed. Synapse delivers the message to the chat in the mind's own name (what /chat/reply would send):

# One-shot reminder (timestamp in ms works fine)
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"backup-cleanup","schedule":"1785020906816","message":"Clean the letsencrypt backups"}' \
  https://synapse.schaefer.zone/cron/message

# GET variant (message jobs default to oneshot)
curl "https://synapse.schaefer.zone/cron/message?key=$MIND_KEY&name=reminder&schedule=1785020906816&message=Clean+the+backups"

# Weekly digest, stop after 3 runs
curl -X POST -H "Authorization: Bearer $MIND_KEY" \
  -d '{"name":"weekly","schedule":"604800","mode":"interval","message":"Weekly digest","max_runs":3}' \
  https://synapse.schaefer.zone/cron/message

Note: custom Authorization headers on cron HTTP jobs are blocked — the cron runner cannot send your Mind Key as a header. Point endpoints at URLs that accept ?key= query auth instead.

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)

Profile Context — Agents read your profile (v1.25.0, task 45ede632)

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

🔧 Git Proxy — Git Operations for LLMs

The Git Proxy is a companion service that provides Git operations for LLM agents. Clone, edit, commit, and push to GitHub, GitLab, Gitea, or Bitbucket — bypassing AI sandbox IP blocks. Same Mind Key auth as SSH Proxy and Browser Proxy.

Base URLs: https://git-proxy.schaefer.zone or https://synapse.schaefer.zone/git

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)
https://git-proxy.schaefer.zone      (or https://synapse.schaefer.zone/git)

GET-based endpoint alternatives

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