Memories API

Base URL: http://localhost:4545/api/v1

All endpoints below require auth once REMEM_API_KEY is set — see Authentication.

Create memory

POST /memories

Fires connection discovery asynchronously in the background; the response returns before discovery finishes.

Field	Type	Default	Notes
`content`	string	required	1–100,000 bytes
`memory_type`	`"short_term"` \| `"long_term"`	`short_term`
`tags`	string[]	`[]`	max 50
`importance`	float 0–1	`0.5`
`emotional_valence`	float -1–1	`0.0`
`arousal`	float 0–1	`0.0`	`>= 0.8` creates a protected “flashbulb” memory — see Memory Lifecycle
`health`	float 0–100	`100.0`	active-forgetting health score
`ttl`	integer (seconds)	none	only meaningful for `short_term`
`source`	string	none	free-text provenance tag
`graph_extraction`	object	none	`{entities: [{name, entity_type?, description?}], relationships: [{source, target, relationship_type?, strength?}]}` — max 100 entities / 200 relationships. Lets the calling LLM supply entities/relationships it already extracted; each entity becomes a linked long-term memory.

{
  "content": "User prefers dark mode.",
  "memory_type": "long_term",
  "tags": ["preference", "ui"],
  "importance": 0.7,
  "emotional_valence": 0.2
}

Response: 201 Created with the full Memory object. 422 on empty/oversized content or too many tags/entities. 500 on embedding or storage failure.

Flashbulb memories

Setting arousal >= 0.8 at creation time force-promotes the memory to long_term, floors importance at 0.9, and exempts it from importance decay and active forgetting for 30 days (tracked via flashbulb_until). This only applies at creation — raising arousal on an existing memory via PUT does not retroactively apply it.

Get memory

GET /memories/{id}?include_connections=false

Response: 200 OK with Memory, or 404 Not Found. Fetching a memory boosts its health by +10 (capped at 100) — see Memory Lifecycle.

Update memory

PUT /memories/{id}

Partial update — body accepts any subset of content, tags, importance, emotional_valence, arousal, health, source.

{
  "content": "User prefers dark mode (updated preference).",
  "importance": 0.9,
  "tags": ["preference", "ui", "confirmed"]
}

Response: 200 OK with the updated Memory, 404 if not found, 422 on oversized content/tags.

Delete memory

DELETE /memories/{id}?hard=false

hard=false (default): soft-archives the memory (archived: true, excluded from search/list/stats). hard=true: permanently removes it.

Response: 200 OK with {"success": true, "message": "memory deleted"}, 404 if not found.

Search memories

POST /memories/search

Field	Type	Default	Notes
`query`	string	required
`search_type`	`"semantic"` \| `"keyword"` \| `"hybrid"`	`semantic`
`limit`	integer	10	max 500
`memory_type`	`"short_term"` \| `"long_term"`	none
`tags`	string[]	`[]`
`min_importance`, `max_importance`	float 0–1	none
`related_to`	UUID	none	boosts memories graph-connected to this memory

{
  "query": "user interface preferences",
  "search_type": "hybrid",
  "limit": 10,
  "tags": ["preference"],
  "memory_type": "long_term",
  "min_importance": 0.5
}

Response: 200 OK

{
  "results": [
    {
      "memory": { "id": "...", "content": "...", "importance": 0.7 },
      "score": 0.91
    }
  ],
  "total": 1
}

422 on empty query or unknown search_type.

List memories

GET /memories?limit=10&offset=0

Query param	Notes
`limit`	default 10, max 100
`offset`	default 0
`memory_type`	`short_term` \| `long_term`
`tags`	comma-separated, e.g. `tags=rust,async`
`min_importance`, `max_importance`	0.0–1.0
`created_after`, `created_before`	RFC-3339, e.g. `2024-01-01T00:00:00Z`
`include_connections`	default `false`

Response: 200 OK with {"total": n, "limit": n, "offset": n, "memories": [Memory, ...]}.

GET /memories/{id}/related?depth=1&relationship_types=&limit=20

See the full traversal and connection-management reference in Connections API.

The `Memory` object

{
  "id": "uuid",
  "content": "string",
  "memory_type": "short_term | long_term",
  "metadata": {
    "created_at": "timestamp",
    "updated_at": "timestamp",
    "accessed_at": "timestamp",
    "access_count": "integer",
    "source": "string | null",
    "tags": ["string"],
    "importance": "float (0-1)",
    "emotional_valence": "float (-1 to 1)",
    "arousal": "float (0-1)",
    "health": "float (0-100)",
    "last_recalled_at": "timestamp | null",
    "flashbulb_until": "timestamp | null",
    "ttl": "integer (seconds) | null"
  },
  "connections": [
    {
      "target_id": "uuid",
      "relationship_type": "related_to | caused_by | part_of | references | contradicts | supports | similar_to | derived_from",
      "strength": "float (0-1)",
      "created_at": "timestamp"
    }
  ]
}

connections is only populated when a request opts in via include_connections=true — list/get calls omit it by default to keep responses small.

Bulk insert

Business — Coming soon. Bulk memory insert (POST /memories/bulk) is not part of the Community Edition today. To insert many memories now, call POST /memories in a loop or in parallel.