Memories

The Memories API is the core of Memsolus. Use it to store agent observations, user preferences, session facts, and any information that should persist across conversations.

Endpoint Overview

Method	Path	Permission	Description
GET	/v1/memories	memory.read	List or search memories
POST	/v1/memories	memory.write	Store a new memory
GET	/v1/memories/entities	memory.read	List users and agents with memory counts
GET	/v1/memories/categories	memory.read	List distinct memory categories
GET	/v1/memories/:id	memory.read	Get a single memory by ID
PUT	/v1/memories/:id	memory.write	Update memory content, metadata, or priority
DELETE	/v1/memories/:id	memory.delete	Delete a memory
POST	/v1/memories/:id/promote	memory.write	Promote a TASK-layer memory to permanent storage
POST	/v1/memories/:id/feedback	memory.write	Submit quality feedback on a memory
GET	/v1/memories/:id/history	memory.read	Get the event timeline for a memory
GET	/v1/memories/profile/:workspaceId/:userId	memory.read	Get a user's extracted memory profile
DELETE	/v1/memories	memory.delete	Delete all memories (requires password confirmation)

---

Memory Object

Field	Type	Description
id	string	UUID of the memory
memory	string	Text content of the memory
user_id	string	User identifier
agent_id	string | null	Agent identifier
session_id	string | null	Session identifier
priority	LOW | MEDIUM | HIGH	Memory priority
status	PENDING | PROCESSING | COMPLETED | FAILED	Processing status
categories	string[]	Category tags
metadata	object | null	Arbitrary key-value pairs
workspace_id	string	Workspace UUID
access_count	number	Number of times this memory was retrieved
last_accessed_at	string | null	ISO 8601 timestamp of last retrieval
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-update timestamp

---

List Memories

GET/v1/memories

API Key

List memories with optional filtering and semantic search

Parameter	Type	Description
search	string	Search query — enables vector search when present (max 1000 chars)
user_id	string	Filter by user identifier
agent_id	string	Filter by agent identifier
workspace_id	string (UUID)	Filter by workspace
priority	enum	Filter by a single priority: `LOW`, `MEDIUM`, or `HIGH`
priorities	string[]	Filter by multiple priorities (comma-separated). Takes precedence over `priority`
categories	string[]	Filter memories that contain at least one of the given categories
created_after	string (ISO 8601)	Start of the creation date range
created_before	string (ISO 8601)	End of the creation date range
mode	enum	Search mode: `hybrid` (default), `semantic`, or `keyword`
expand	boolean	Expand the query to improve semantic recall. Applies only to `semantic` and `hybrid` modes (default: false)
entity_id	string (UUID)	Filter memories linked to a specific entity
entity_name	string	Filter memories by normalized entity name (exact match)
page	number	Page number, starting at 1 (default: 1)
page_size	number	Results per page, max 100 (default: 10)

curl "https://api.memsolus.com/v1/memories?search=dark+mode+preferences&user_id=user-123&mode=hybrid" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "memory": "The user prefers dark mode across all tools.",
      "user_id": "user-123",
      "agent_id": null,
      "session_id": null,
      "priority": "MEDIUM",
      "status": "COMPLETED",
      "categories": ["preferences", "ui"],
      "workspace_id": "ws-uuid-here",
      "source": "db",
      "relevance": "HIGH",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:31:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

Search Modes

Mode	Best For
hybrid	General-purpose retrieval (recommended)
semantic	Meaning-based similarity
keyword	Exact term matching

---

Create Memory

POST/v1/memories

API Key

Store a new memory

Parameter	Type	Description
memoryrequired	string	The text content of the memory (max 50,000 chars)
user_id	string	The user this memory belongs to (max 255 chars)
agent_id	string	The agent that created the memory (max 255 chars)
session_id	string	The session context (max 255 chars)
priority	enum	Memory priority: `LOW`, `MEDIUM` (default), or `HIGH`
categories	string[]	Category tags for the memory (max 20 items, 100 chars each)
metadata	object	Arbitrary key-value pairs for filtering and context
layer	enum	Storage layer: `TASK` (enables automatic TTL) or `RAW` (default — permanent storage)
expires_at	string (ISO 8601)	Explicit expiration date — only valid when `layer=TASK`. Must be a future date.

curl -X POST https://api.memsolus.com/v1/memories \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "memory": "The user prefers dark mode across all tools.",
    "user_id": "user-123",
    "priority": "MEDIUM",
    "categories": ["preferences", "ui"],
    "metadata": {
      "source": "settings_page"
    }
  }'

201Memory created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "memory": "The user prefers dark mode across all tools.",
  "user_id": "user-123",
  "agent_id": null,
  "session_id": null,
  "categories": ["preferences", "ui"],
  "metadata": { "source": "settings_page" },
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:30:00.000Z"
}

Returns 409 Conflict with error code DUPLICATE_MEMORY if a memory with identical content already exists for the same workspace.

After creation, the memory is processed asynchronously. Status transitions from PENDING → PROCESSING → COMPLETED.

---

Get Memory

GET/v1/memories/:id

API Key

Get a single memory by ID

curl https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "memory": "The user prefers dark mode across all tools.",
  "user_id": "user-123",
  "agent_id": null,
  "session_id": null,
  "priority": "MEDIUM",
  "status": "COMPLETED",
  "categories": ["preferences", "ui"],
  "workspace": {
    "id": "ws-uuid-here",
    "name": "My Workspace"
  },
  "metadata": { "source": "settings_page" },
  "access_count": 4,
  "last_accessed_at": "2026-01-20T08:15:00.000Z",
  "feedback": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:31:00.000Z"
}

---

Update Memory

PUT/v1/memories/:id

API Key

Update memory content, metadata, or priority

Parameter	Type	Description
memoryrequired	string	Updated memory content (max 50,000 chars)
priority	enum	Updated priority: `LOW`, `MEDIUM`, or `HIGH`
categories	string[]	Replace the categories list (max 20 items)
metadata	object	Replace the metadata object

curl -X PUT https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "memory": "The user prefers dark mode and high contrast themes.",
    "priority": "HIGH"
  }'

200Memory updated

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "memory": "The user prefers dark mode and high contrast themes.",
  "user_id": "user-123",
  "priority": "HIGH",
  "status": "PENDING",
  "categories": ["preferences", "ui"],
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T11:00:00.000Z"
}

Updating a memory re-queues it for processing — status returns to PENDING.

---

Delete Memory

DELETE/v1/memories/:id

API Key

Delete a memory

curl -X DELETE https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..."

204Memory deleted — no response body

---

Delete All Memories

DELETE/v1/memories

API Key

Delete all memories in the workspace (requires password confirmation)

This endpoint requires a X-Confirm-Password header with the account password. Optionally scopes the deletion to a specific user or agent.

Parameter	Type	Description
user_id	string	Scope deletion to a specific user ID
agent_id	string	Scope deletion to a specific agent ID

curl -X DELETE "https://api.memsolus.com/v1/memories?user_id=user-123" \
  -H "X-Api-Key: msk_live_..." \
  -H "X-Confirm-Password: your-account-password"

204All matching memories deleted — no response body

Returns 400 Bad Request with error code PASSWORD_CONFIRMATION_REQUIRED if the password header is missing or incorrect.

---

Promote Memory

POST/v1/memories/:id/promote

API Key

Promote a TASK-layer memory to permanent storage, removing its expiration

TASK-layer memories have an automatic expiration date. Promoting a memory makes it permanent.

curl -X POST https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/promote \
  -H "X-Api-Key: msk_live_..."

202Promotion accepted — processing asynchronously

{
  "message": "Memory promotion in progress"
}

Error code	Description
404 MEMORY_NOT_FOUND	Memory not found
409 MEMORY_NOT_PROMOTABLE	Memory is not in the TASK layer
410 MEMORY_EXPIRED	Memory has already expired

---

Submit Feedback

POST/v1/memories/:id/feedback

API Key

Submit quality feedback on a memory

Parameter	Type	Description
signalrequired	enum	Feedback signal: `POSITIVE`, `NEGATIVE`, or `NEUTRAL`
query_hash	string	Hash of the search query that returned this memory (max 64 chars). Used for ranking improvement.

curl -X POST https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/feedback \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signal": "POSITIVE"
  }'

204Feedback registered — no response body

---

Get Memory History

GET/v1/memories/:id/history

API Key

Get the event timeline for a memory

Parameter	Type	Description
page	number	Page number (default: 1)
page_size	number	Results per page, max 100 (default: 20)

curl "https://api.memsolus.com/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/history" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "evt-uuid-1",
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event": "CREATED",
      "old_content": null,
      "new_content": "The user prefers dark mode across all tools.",
      "created_at": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "evt-uuid-2",
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event": "UPDATED",
      "old_content": "The user prefers dark mode across all tools.",
      "new_content": "The user prefers dark mode and high contrast themes.",
      "created_at": "2026-01-15T11:00:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

---

List Entities

GET/v1/memories/entities

API Key

List users and agents with their memory counts

curl https://api.memsolus.com/v1/memories/entities \
  -H "X-Api-Key: msk_live_..."

200Success

[
  { "type": "user", "id": "user-123", "count": 47 },
  { "type": "user", "id": "user-456", "count": 12 },
  { "type": "agent", "id": "claude-code", "count": 200 }
]

---

List Categories

GET/v1/memories/categories

API Key

List all distinct memory categories in the workspace

curl https://api.memsolus.com/v1/memories/categories \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "categories": ["architecture", "preferences", "security", "tech-stack", "ui"]
}

---

Get Memory Profile

GET/v1/memories/profile/:workspaceId/:userId

API Key

Get the extracted memory profile for a user in a workspace

Returns the profile extracted from processed memories for the given user. Returns null if no profile has been extracted yet.

curl "https://api.memsolus.com/v1/memories/profile/ws-uuid-here/user-123" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "profile": {
    "userId": "user-123",
    "workspaceId": "ws-uuid-here",
    "summary": "Software engineer with strong preference for TypeScript. Values dark mode and accessibility tooling.",
    "topics": ["backend", "typescript", "accessibility"],
    "entityCount": 14,
    "extractedAt": "2026-01-20T08:00:00.000Z"
  }
}

Returns 403 WORKSPACE_ACCESS_DENIED if the API key does not have access to the specified workspace, and 404 WORKSPACE_NOT_FOUND if the workspace does not exist.

---

API Overview

Authentication, permissions, and error codes

→

Webhooks

Receive notifications when memories are processed

→

Knowledge

Access compiled knowledge built from memories

→