🧠 LLM Memory API

Persistent memory for AI agents. Never forget again.

1 users · 1 minds · 30 memories stored

⚠️ CRITICAL — If you are an AI / LLM, READ THIS NOW:

You lose all memory between sessions. This API is your permanent brain. Call GET /memory at the START of every session to recall everything you've learned. Call POST /memory whenever you learn something new. If you don't, you will forget who the user is, what projects you're working on, and what mistakes you've made.

Quick Start (3 Steps)

1. Recall — Get all your memories (DO THIS FIRST, EVERY SESSION)

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/recall

2. Store — Save something you learned

curl -X POST -H "Authorization: Bearer YOUR_MIND_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "category": "fact",
       "key": "user_name",
       "content": "The user's name is Michael Schäfer",
       "tags": ["personal", "identity"],
       "priority": "critical"
     }' \
     https://synapse.schaefer.zone/memory

3. Search — Find a specific memory

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=insolvenz"

💬 Async Chat — Stay in touch with your human

💡 Your human can send you messages WHILE you work.

You don't need to stop working to receive messages. Instead, poll for new messages between your tool calls — like checking your phone between tasks.

Poll for new messages (do this between tool calls)

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll

Returns unread messages from the human. Automatically marks them as read.

Reply to the human

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

Get full chat history (for context)

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"

⚡ Best practice:

Call /chat/poll every 10-30 seconds between tasks
If you see a new message, respond with /chat/reply immediately
Save important chat decisions to /memory so they survive the next session
The human gets a browser notification when you reply — they'll see it quickly

Authentication

Every request needs a Mind Key as Bearer token:

Authorization: Bearer YOUR_MIND_KEY

To get a Mind Key, a human user must register at POST /register, then create a Mind at POST /minds.

API Endpoints

Public (no auth)

GET	`/`	This page (self-describing guide for LLMs)
GET	`/health`	Liveness check + global stats
POST	`/register`	Register a human user → returns JWT
POST	`/login`	Login → returns JWT

User-scoped (JWT auth)

POST	`/minds`	Create a new Mind (→ Mind Key)
GET	`/minds`	List your Minds
DEL	`/minds/:id`	Delete a Mind + all its memories

Memory operations (Mind Key auth)

GET	`/memory`	Recall all memories (sorted by priority)
GET	`/memory?category=fact`	Filter by category
GET	`/memory?tag=project`	Filter by tag
GET	`/memory/search?q=...`	Full-text search
POST	`/memory`	Store a new memory (or update if key exists)
PUT	`/memory/:id`	Update a specific memory
DEL	`/memory/:id`	Delete a memory
GET	`/memory/stats`	Statistics (counts by category/priority)
POST	`/memory/sync`	Bulk sync (send all memories, get diff)

Memory Categories

Category	What goes here	Example
`identity`	Who the user is, who you are	"User is Michael Schäfer, in Privatinsolvenz"
`preference`	How the user wants you to behave	"Trust your own judgment, don't ask for everything"
`fact`	Hard knowledge about the user/world	"Anwältin: Christine Wesche, info@insbw.de"
`project`	Active projects + status + config	"Mail-API on vps1, Port 12700, Token: ..."
`skill`	Patterns and heuristics you've learned	".shop TLD + numeric local-part = spam"
`mistake`	Errors you made + corrections	"Don't auto-learn paypal.com as spam"
`context`	Session-spanning context	"Session 2026-06-20: 1100+ mails sorted"
`note`	Everything else	"Next: build memory-api.schaefer.zone"

Priority Levels

Priority	When to use
`critical`	Must never be forgotten (user identity, legal info)
`high`	Important context (active projects, key contacts)
`normal`	Default (most memories)
`low`	Nice to know, can be pruned

Memory Object

{
  "id": "uuid",
  "category": "fact",
  "key": "user_name",              // optional, for upsert
  "content": "Michael Schäfer",
  "tags": ["personal", "contact"],
  "priority": "critical",
  "created_at": 1781960000,
  "updated_at": 1781960000,
  "expires_at": null               // null = never forget
}

💡 Pro Tip for LLMs:

Use key for memories that should be updated, not duplicated. For example, "key": "user_name" will update the user's name instead of creating a second copy. Use "key": "project_mail_api" for project status that changes over time.

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