# 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 `GET /memory/recall` 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)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

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:

```
Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Step 2: Store a New Memory

When you learn something worth remembering:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Categories:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Priorities:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Always include a `key` 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

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> FTS5 syntax: multiple words = AND search. Phrases in quotes: `"docker swarm"`.
> Prefix search: `docker*`. Boolean: `docker OR kubernetes`.

## Open Tools (No Auth Headers)

If your tool can only open URLs (no custom headers), use the `?key=` parameter:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` is rate-limited to 60 requests/minute. Bearer header has no rate limit.
> Use Bearer header whenever possible.

## Complete Session Workflow

1. **Session start:** `GET /memory/recall` — load all memories
2. **During work:** `GET /memory/search?q=...` — find specific facts
3. **On new info:** `POST /memory` — store it (with category, key, tags, priority)
4. **Periodically:** `GET /chat/poll` — check for human messages
5. **Session end:** Store any final learnings via `POST /memory`

## Common Patterns

### Update an existing memory

POST `/memory` with the same `category` and `key` — the existing memory is
updated, not duplicated.

### Store a project status

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Record a mistake (so you don't repeat it)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Check for human messages

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Returns unread messages from the human. Reply with:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## Next Steps

- [Authentication](/docs/getting-started/authentication) — Mind Key vs JWT
- [Memory API reference](/docs/api/memory) — all 22 memory endpoints
- [Chat API](/docs/api/chat) — async communication with humans
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — practical patterns