Search & Retrieval

Find memories using semantic search or navigate the keypath hierarchy for structured retrieval.

POST/memories/searchSemantic search

POST/keypathsGet by keypath (recursive)

GET/statusSystem status

Semantic Search

POST/memories/search

Search across all memories using natural language. The query is converted to a vector embedding and matched against stored memories using cosine similarity.

Request Body

Parameter	Type	Required	Description
query	string	Required	Natural language search query. If empty, returns all memories ordered by keypath.
limit	integer	Default: 5	Maximum results (1-20).
categories	string[]	Optional	Filter by categories.
project_id	string	Optional	Filter by project.
keypath_prefix	string	Optional	Filter by keypath prefix.
include_superseded	boolean	Default: false	Include older superseded versions.

Request

curl -X POST https://api.memstate.ai/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "query": "how does the user sign up and what authentication method do we use",
    "project_id": "my-saas",
    "limit": 5
  }'

200 OK

{
  "results": [
    {
      "id": "mem_auth01",
      "summary": "OAuth2 authentication with Google and GitHub providers",
      "keypath": "auth.provider",
      "score": 0.94,
      "version": 1,
      "created_at": "2026-02-10T09:00:00Z"
    },
    {
      "id": "mem_auth02",
      "summary": "User registration flow with email verification",
      "keypath": "auth.registration",
      "score": 0.87,
      "version": 1,
      "created_at": "2026-02-10T09:15:00Z"
    }
  ],
  "total_found": 2,
  "query": "how does the user sign up and what authentication method do we use"
}

Search tips

Use natural language for the best results. The search uses semantic similarity, so “how do users log in” will match memories about authentication even if they don't contain the exact words “log in”.

Empty query: If you pass an empty string "" as the query, the endpoint switches to "browse" mode, returning all memories ordered alphabetically by keypath.

Get by Keypath (Recursive)

POST/keypaths

Retrieve memories at a keypath with optional recursive expansion and time-travel. Returns a map of keypath to summary for efficient context loading.

Request Body

Parameter	Type	Required	Description
project_id	string	Required	Project to query.
keypath	string	Required	Root keypath to retrieve.
recursive	boolean	Default: false	Include all child keypaths.
at_revision	integer	Optional	Time-travel: get state at a specific revision number.

Request (Recursive)

curl -X POST https://api.memstate.ai/api/v1/keypaths \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "project_id": "my-saas",
    "keypath": "auth",
    "recursive": true
  }'

200 OK

{
  "memories": {
    "auth": "Authentication system overview with multi-provider support",
    "auth.provider": "OAuth2 with Google and GitHub providers",
    "auth.registration": "User registration with email verification",
    "auth.session": "JWT sessions with 15-minute access + 7-day refresh tokens"
  },
  "total_count": 4,
  "revision_number": 23
}

Time-Travel Queries

Use at_revision to retrieve the memory state at any point in history. This is useful for understanding how your project's knowledge evolved.

Request (Time-Travel)

curl -X POST https://api.memstate.ai/api/v1/keypaths \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mst_your_key" \
  -d '{
    "project_id": "my-saas",
    "keypath": "auth",
    "recursive": true,
    "at_revision": 10
  }'

What are revisions?

Each ingestion creates a new revision number. You can list all revisions with the GET /projects/{id}/revisions endpoint to find the revision you want to query.

System Status

GET/status

Get the current system status including memory count, project count, and available features.

Request

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

200 OK

{
  "status": "ok",
  "memory_count": 156,
  "project_count": 4,
  "storage_backend": "postgres",
  "features": {
    "conflict_detection": true,
    "llm_processing": true
  }
}