Remember API

The primary way to save information to Memstate. Pass any text or markdown and our custom-trained AI models automatically extract facts, organize them into a hierarchical keypath structure, detect conflicts, and version everything.

remember vs store

Use POST /memories/remember when you have raw content (task summaries, docs, meeting notes) and want automatic organization. Use POST /memories/store when you already know the exact keypath and value you want to set.

POST/memories/remember
GET/jobs/{job_id}

Remember Content

POST/memories/remember

Submit any text or markdown for processing. Memstate's custom-trained AI analyzes the content to:

  • Extract meaningful keypaths from the content structure
  • Generate compressed summaries for each extracted memory
  • Detect conflicts with existing memories at the same keypaths
  • Handle versioning and conflict resolution automatically -- every change is preserved in history
  • Create a project revision for time-travel queries

Request Body

ParameterTypeRequiredDescription
project_idstringRequiredProject to remember into.
contentstringRequiredRaw content to process (README, docs, meeting notes, task summaries, etc.).
sourcestringOptionalContent type hint for better extraction: "readme", "docs", "meeting", "agent", "code".
contextstringOptionalAdditional 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": "# Authentication\n\nWe use Auth0 for authentication with the following setup:\n- Social login via Google and GitHub\n- Email/password as fallback\n- JWT tokens with 1-hour expiry\n- Refresh tokens stored in httpOnly cookies\n\n## Rate Limiting\n\nAPI endpoints are rate limited to 100 requests per minute per user. Premium users get 1000 requests per minute.",
    "source": "docs",
    "context": "Extracted from project README"
  }'
202 Accepted (async)
{
  "job_id": "job_abc123",
  "status": "pending",
  "message": "Ingestion job enqueued successfully",
  "project_id": "my-saas"
}
200 OK (sync fallback)
{
  "ingestion_id": "ing_abc123",
  "status": "complete",
  "memories_created": ["mem_auth01", "mem_auth02", "mem_rate01"],
  "keypaths_created": ["auth.provider", "auth.tokens", "api.rate_limiting"],
  "keypaths_updated": [],
  "revision_number": 5,
  "conflicts": [],
  "processing_time_ms": 3200,
  "message": "Ingested 3 memories across 3 keypaths"
}

Conflict Detection

When content conflicts with existing memories, the system classifies each conflict:

none / additive

New information that doesn't conflict. Stored alongside existing memories.

supersede

Updated information that replaces the existing memory. Previous version is preserved in history.

contradiction

Contradictory information. Both versions are stored in the version chain, with the newer version automatically taking precedence. Use POST /memories/history to inspect the full chain.

Response with conflicts
{
  "ingestion_id": "ing_def456",
  "status": "complete",
  "memories_created": ["mem_auth03"],
  "keypaths_created": [],
  "keypaths_updated": ["auth.provider"],
  "revision_number": 6,
  "conflicts": [
    {
      "keypath": "auth.provider",
      "type": "supersede",
      "existing_summary": "Auth0 with social login and email/password",
      "new_summary": "Migrated to Clerk with social login only"
    }
  ],
  "processing_time_ms": 2800,
  "message": "Ingested 1 memory, 1 conflict resolved (superseded)"
}

Check Job Status

GET/jobs/{job_id}

Remember requests are processed asynchronously. The endpoint returns a job_id immediately and processes in the background (~15-20 seconds). Use this endpoint to poll for completion.

Path Parameters

ParameterTypeRequiredDescription
job_idstringRequiredThe job ID returned from a remember request.
Request
curl https://api.memstate.ai/api/v1/jobs/job_xyz789 \
  -H "X-API-Key: mst_your_key"

Async Processing

Remember requests return 202 Accepted with a job_id. Poll the jobs endpoint every 2-3 seconds until status is complete or error. Most jobs complete in 15-20 seconds.

Example: Document Processing Pipeline

Here's a complete example of building a document processing pipeline using the remember API in Python:

Python - Document Pipeline
import requests
import time

API_KEY = "mst_your_key"
BASE_URL = "https://api.memstate.ai/api/v1"
HEADERS = {"Content-Type": "application/json", "X-API-Key": API_KEY}

def remember(project_id: str, content: str, source: str = "docs"):
    """Remember content and wait for async processing to complete."""
    response = requests.post(
        f"{BASE_URL}/memories/remember",
        headers=HEADERS,
        json={
            "project_id": project_id,
            "content": content,
            "source": source,
        },
    )
    result = response.json()

    # Handle async processing (202 Accepted)
    if result.get("status") == "pending":
        job_id = result["job_id"]
        while True:
            time.sleep(3)
            status = requests.get(
                f"{BASE_URL}/jobs/{job_id}", headers=HEADERS
            ).json()
            if status.get("status") in ("complete", "error"):
                return status

    return result

def get_project_context(project_id: str, keypath: str = ""):
    """Get all memories under a keypath."""
    response = requests.post(
        f"{BASE_URL}/keypaths",
        headers=HEADERS,
        json={
            "project_id": project_id,
            "keypath": keypath or "",
            "recursive": True,
        },
    )
    return response.json()

# Usage
result = remember("my-saas", open("README.md").read(), "readme")
print(f"Created {len(result.get('memories_created', []))} memories")
print(f"Keypaths: {result.get('keypaths_created', [])}")

# Later: retrieve all project context
context = get_project_context("my-saas")
for keypath, summary in context["memories"].items():
    print(f"  {keypath}: {summary}")