# 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 `GET /memory/recall` 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 |
|----------|----------|
| `identity` | User name, role, contact info, preferences about self |
| `preference` | Likes, dislikes, working style, communication prefs |
| `fact` | Verifiable facts (project details, dates, URLs) |
| `project` | Project status, milestones, architecture |
| `skill` | Things the user is good at |
| `mistake` | Past errors — avoid repeating |
| `context` | Session-relevant context |
| `note` | Misc notes |

## Priorities

- `low` — nice to know
- `normal` — default
- `high` — important
- `critical` — 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.

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

Response (text/plain):

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

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

...
```

### POST /memory

Store a new memory or update an existing one (same category + key = update).

```bash
curl -X POST https://synapse.schaefer.zone/memory \
  -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": ["person", "identity"],
    "priority": "critical"
  }'
```

Response: `{ "id": "mem_001", "status": "stored" }`

### GET /memory

List memories with optional filters.

```bash
# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

# Filter by tag
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?tag=docker"
```

### PUT /memory/:id

Update a specific memory by ID.

```bash
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated content", "priority": "high"}'
```

### DELETE /memory/:id

Delete a single memory.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mem_001
```

## Search Endpoints

### GET /memory/search

Full-text search using FTS5.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"
```

FTS5 syntax:

- Multiple words = AND: `docker swarm`
- Phrase: `"docker swarm"`
- Prefix: `docker*`
- Boolean: `docker OR kubernetes`
- Exclude: `docker -swarm`

### GET /memory/semantic-search

Conceptual search using embeddings (slower than FTS5 but understands meaning).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"
```

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.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"
```

### GET /memory/related/:id

Find memories related to a specific memory (via shared tags).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/related/mem_001
```

## Sync & Diff

### GET /memory/diff

Incremental sync — returns memories changed since a timestamp.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/diff?since=1700000000"
```

Response: `{ "added": [...], "updated": [...], "deleted": [...] }`

### POST /memory/sync

Apply a diff from another instance (for self-hosted sync).

```bash
curl -X POST https://synapse.schaefer.zone/memory/sync \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"added": [...], "updated": [...], "deleted": [...]}'
```

## Bulk Operations

### POST /memory/bulk-delete

Delete multiple memories by ID.

```bash
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'
```

### POST /memory/embed-batch

Generate embeddings for memories that don't have them yet (for semantic search).

```bash
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
```

### GET /memory/embed-batch-status

Check embedding generation progress.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status
```

## Verification

Memories have a `verified` flag. Agent-stored memories default to unverified
(`source=agent`); human-stored memories are verified (`source=user`).

### POST /memory/verify

Mark a memory as verified (requires JWT, not Mind Key).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \
  -H "Authorization: Bearer YOUR_JWT"
```

### POST /memory/unverify

Mark a memory as unverified (requires JWT).

```bash
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \
  -H "Authorization: Bearer YOUR_JWT"
```

### GET /memory/unverified

List memories awaiting human verification.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/unverified?limit=100"
```

## Statistics & Audit

### GET /memory/stats

Aggregate statistics for the current mind.

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

Returns: `{ "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }`

### GET /memory/audit

Audit log of all state-changing operations.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"
```

### GET /memory/contradictions

Detect potential contradictions in stored memories.

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

### GET /memory/expiring

List memories with expiry dates approaching.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/expiring?within=7d"
```

## Health & Export

### GET /memory/health

Quick health check for memory system.

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

### GET /memory/mind-export

Full JSON export of all memories (for backup).

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/mind-export > backup.json
```

### POST /memory/compact

Compact similar memories (auto-summarization).

```bash
curl -X POST https://synapse.schaefer.zone/memory/compact \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'
```

## Next Steps

- [Quick Start for LLMs](/docs/getting-started/quick-start-llm)
- [Memory Best Practices](/docs/guides/memory-best-practices)
- [FTS5 Search](/docs/concepts/fts5-search)
- [Semantic Search](/docs/concepts/semantic-search)