Memories API

The core endpoints for storing, retrieving, updating, and browsing memories.

POST/memories/rememberAuto-extract and remember content (recommended)

POST/memories/storeStore a memory at a specific keypath

GET/memories/{id}Get by ID

GET/memories/keypath/{keypath}Get by keypath

POST/memories/browseBrowse by prefix

POST/memories/historyVersion history

POST/memories/deleteSoft-delete a memory

Remember Content

POST/memories/remember

The recommended way to save information. Pass any text or markdown and Memstate's custom-trained AI automatically extracts facts, organizes them into keypaths, detects conflicts, and versions everything. No manual keypath management required.

This is the primary API

Use /memories/remember for task summaries, meeting notes, README files, or any freeform content. Use /memories/store when you need to set a specific keypath to a specific value.

Request Body

Parameter	Type	Required	Description
project_id	string	Required	Project to remember into.
content	string	Required	Raw content to process (README, docs, meeting notes, task summaries, etc.).
source	string	Optional	Content type hint for better extraction: "readme", "docs", "meeting", "agent", "code".
context	string	Optional	Additional context to guide keypath extraction (e.g., "Architecture decision from sprint planning").

Request

curl -X POST https://api.memstate.ai/api/v1/memories/remember \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "project_id": "my-saas",
    "content": "## Auth\n\nWe use Auth0 with social login (Google, GitHub) and email/password fallback. JWT tokens expire in 1 hour. Refresh tokens are stored in httpOnly cookies.",
    "source": "agent"
  }'

202 Accepted (async)

{
  "job_id": "job_abc123",
  "status": "pending",
  "message": "Ingestion job enqueued successfully",
  "project_id": "my-saas"
}

Async Processing

Remember requests return 202 Accepted with a job_id. Poll GET /jobs/{job_id} every 2-3 seconds until complete. Most jobs finish in 15-20 seconds.

Store a Memory

POST/memories/store

Store a value at a specific keypath. Use this when you already know the exact keypath and value you want to set. If a memory already exists at that keypath within the same project, it will be automatically superseded and the previous version preserved.

Request Body

Parameter	Type	Required	Description
content	string	Required	The value to store. Keep it short and specific for best results.
keypath	string	Required	Dot-separated hierarchical path (e.g., "config.database.port"). Lowercase with dots only.
project_id	string	Optional	Project to scope this memory to. Provides namespace isolation.
category	string	Optional	Optional category for classification (e.g., "architecture", "decision", "config").
topics	string[]	Optional	Optional list of topic tags for additional classification.

Request

curl -X POST https://api.memstate.ai/api/v1/memories/store \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "content": "Stripe with Checkout and Customer Portal",
    "keypath": "billing.provider",
    "project_id": "my-saas",
    "category": "architecture"
  }'

Response

200 OK

{
  "memory_id": "mem_abc123def456",
  "action": "created",
  "version": 1,
  "message": "Memory stored at billing.provider"
}

Automatic features

When you store a memory, the system automatically:

Generates a vector embedding for semantic search
Creates a compressed summary
Detects conflicts with existing memories at the same keypath
Preserves the full version history -- every change is auditable via POST /memories/history

Get Memory by ID

GET/memories/{id}

Retrieve the full content of a specific memory by its unique ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Required	The unique memory ID (e.g., "mem_abc123def456").

Request

curl https://api.memstate.ai/api/v1/memories/mem_abc123def456 \
  -H "X-API-Key: mst_your_key"

200 OK

{
  "id": "mem_abc123def456",
  "content": "Stripe with Checkout and Customer Portal",
  "summary": "Stripe-based subscription billing with Checkout and Customer Portal",
  "keypath": "billing.provider",
  "category": "architecture",
  "version": 1,
  "project_id": "my-saas",
  "created_at": "2026-02-15T10:30:00Z",
  "updated_at": "2026-02-15T10:30:00Z"
}

Get Memory by Keypath

GET/memories/keypath/{keypath}

Get the latest (non-superseded) memory at a specific keypath. The keypath is passed as a URL path with dots replaced by slashes or kept as-is.

Path Parameters

Parameter	Type	Required	Description
keypath	string	Required	The keypath to look up (e.g., "billing.provider").

Query Parameters

Parameter	Type	Required	Description
project_id	string	Optional	Filter by project.

Request

curl "https://api.memstate.ai/api/v1/memories/keypath/billing.provider?project_id=my-saas" \
  -H "X-API-Key: mst_your_key"

Browse Memories

POST/memories/browse

Browse all memories under a keypath prefix. Returns summaries for efficient context loading.

Request Body

Parameter	Type	Required	Description
keypath_prefix	string	Required	Keypath prefix to browse (e.g., "billing" matches "billing.provider", "billing.webhooks").
project_id	string	Optional	Filter by project.
limit	integer	Optional	Maximum results to return.

Request

curl -X POST https://api.memstate.ai/api/v1/memories/browse \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "keypath_prefix": "billing",
    "project_id": "my-saas"
  }'

200 OK

{
  "memories": [
    {
      "id": "mem_new789",
      "summary": "Stripe-based subscription billing",
      "keypath": "billing.provider",
      "version": 2
    },
    {
      "id": "mem_wh001",
      "summary": "Webhook handlers for payment events",
      "keypath": "billing.webhooks",
      "version": 1
    }
  ],
  "total_found": 2,
  "keypath_prefix": "billing"
}

Version History

POST/memories/history

Get the complete version history for a memory or keypath. Shows how information has evolved over time.

Request Body

Parameter	Type	Required	Description
memory_id	string	Optional	Get history by memory ID.
keypath	string	Optional	Get history by keypath (alternative to memory_id).
project_id	string	Optional	Filter by project (required when using keypath).

Request

curl -X POST https://api.memstate.ai/api/v1/memories/history \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "keypath": "billing.provider",
    "project_id": "my-saas"
  }'

200 OK

{
  "versions": [
    {
      "id": "mem_abc123def456",
      "summary": "Stripe-based subscription billing",
      "version": 1,
      "created_at": "2026-01-15T08:00:00Z",
      "superseded_by": "mem_new789"
    },
    {
      "id": "mem_new789",
      "summary": "LemonSqueezy subscription billing with JS SDK",
      "version": 2,
      "created_at": "2026-02-15T10:30:00Z",
      "superseded_by": null
    }
  ],
  "total_versions": 2
}

Soft-Delete a Memory

POST/memories/delete

Soft-delete a memory by keypath. Creates a tombstone version with empty content, preserving the full version history. Optionally delete an entire subtree recursively.

Request Body

Parameter	Type	Required	Description
keypath	string	Required	Keypath to delete (e.g., "project.myapp.config.port").
project_id	string	Required	Project containing the memory.
recursive	boolean	Default: false	If true, delete the keypath and all its children.

Request

curl -X POST https://api.memstate.ai/api/v1/memories/delete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "keypath": "project.my-saas.billing.old_provider",
    "project_id": "my-saas",
    "recursive": false
  }'

200 OK

{
  "deleted_keypaths": ["project.my-saas.billing.old_provider"],
  "deleted_count": 1,
  "message": "Soft-deleted 1 memory(ies) at keypath 'project.my-saas.billing.old_provider'"
}

Tombstone versioning

Deleted memories are not erased. A new version with empty content and is_deleted: true is created. The previous versions remain visible in the version history. To un-delete, simply store a new value at the same keypath using /memories/store.