Memory endpoints

Base path: /api/v1/memory

POST /v1/memory/add

Store one memory. Auto-embeds the content and optionally flags conflicts.

Body

{
  "content":    "User prefers dark mode",
  "agent_id":   "myai",
  "user_id":    "alice",            // optional
  "session_id": "sess_abc",         // auto-generated if omitted
  "tags":       ["pref", "ui"],
  "category":   "preferences",
  "importance": 0.8,
  "layer":      "l3",
  "metadata":   { "source": "onboarding" },
  "expire_at":  null
}

Response 201

{
  "data": {
    "id_memory":     "b412f2e5-…",
    "agent_id":      "myai",
    "session_id":    "sess_abc",
    "created_at":    "2026-04-15T01:51:00Z",
    "conflict_with": null
  },
  "meta": { "warnings": [] }
}

POST /v1/memory/read

Semantic search. Cosine similarity over pgvector.

{
  "query":    "what does the user prefer?",
  "agent_id": "myai",
  "scope":    "agent",          // agent | all_agents | all_users | project
  "top_k":    5,
  "threshold": 0.3,
  "category": null,
  "layer":    null
}

Returns a sorted list of memories with a score field (0–1).

GET /v1/memory

List with filters and pagination.

GET /v1/memory/<id>

Fetch one memory.

PATCH /v1/memory/<id>

Update any subset of fields. Changing content bumps current_version and snapshots a new row into memory_versions.

{ "content": "…", "tags": [...], "importance": 0.9, "expire_at": "2026-12-31T00:00:00Z" }

DELETE /v1/memory/<id>

Removes the memory and cascades to its versions.

GET /v1/memory/<id>/history

Full version log, oldest first.

[
  { "version_num": 1, "change_type": "created", "content": "…", "changed_by": "myai", "created_at": "…" },
  { "version_num": 2, "change_type": "updated", "content": "…", "changed_by": "api",  "created_at": "…" }
]

GET /v1/usage

Account totals for the current billing period:

{
  "plan": "developer",
  "ops_used_month":   12345,
  "memories_stored":  678,
  "project_memories": 678,
  "ops_reset_at":     "2026-05-01T00:00:00Z"
}