APIQuickstartTutorial

API Quickstart — Memories in 5 Minutes

5 min readBy Mohammad Saquib Daiyan

The PersistMemory REST API lets you store, search, and manage memories from any language or platform. This quickstart gets you from zero to working API calls in five minutes, with examples in curl, Python, and TypeScript.

Get Your API Key

Sign up at persistmemory.com and grab your API key from the dashboard. All requests require a Bearer token in the Authorization header. The base URL for all endpoints is:

https://backend.persistmemory.com

Set your API key as an environment variable so the examples below work directly:

export PERSISTMEMORY_API_KEY="your-api-key-here"

Store a Memory

Send a POST request to /mcp/addMemory with the content you want to store. PersistMemory automatically generates embeddings and indexes the memory for semantic search.

curl

curl -X POST https://backend.persistmemory.com/mcp/addMemory \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space": "preferences",
    "title": "Editor preferences",
    "text": "User prefers dark mode and Vim keybindings in all editors."
  }'

Python

import os
import requests

API_KEY = os.environ["PERSISTMEMORY_API_KEY"]
BASE_URL = "https://backend.persistmemory.com"

response = requests.post(
    f"{BASE_URL}/mcp/addMemory",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "space": "preferences",
        "title": "Editor preferences",
        "text": "User prefers dark mode and Vim keybindings.",
    },
)

memory = response.json()
print(f"Stored memory ID: {memory['id']}")

TypeScript

const API_KEY = process.env.PERSISTMEMORY_API_KEY!;
const BASE_URL = "https://backend.persistmemory.com";

const response = await fetch(`${BASE_URL}/mcp/addMemory`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "preferences",
    title: "Editor preferences",
    text: "User prefers dark mode and Vim keybindings.",
  }),
});

const memory = await response.json();
console.log(`Stored memory ID: ${memory.id}`);

Search Memories

Search uses vector similarity to find memories semantically related to your query. A search for "editor settings" will match memories about Vim keybindings and dark mode even without exact keyword overlap.

curl

curl -X POST https://backend.persistmemory.com/mcp/search \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"space": "preferences", "q": "What are the user\'s editor preferences?", "top_k": 5}'

Python

response = requests.post(
    f"{BASE_URL}/mcp/search",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "space": "preferences",
        "q": "What are the user's editor preferences?",
        "top_k": 5,
    },
)

results = response.json()["memories"]
for mem in results:
    print(f"[{mem['score']:.3f}] {mem['text']}")

TypeScript

const response = await fetch(`${BASE_URL}/mcp/search`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    space: "preferences",
    q: "What are the user's editor preferences?",
    top_k: 5,
  }),
});

const { memories } = await response.json();
for (const mem of memories) {
  console.log(`[${mem.score.toFixed(3)}] ${mem.text}`);
}

Each result includes a score from 0 to 1. Scores above 0.8 indicate a strong semantic match. Results are sorted by score in descending order.

List All Memories

Retrieve all memories in a space, sorted by creation date (newest first):

# curl
curl "https://backend.persistmemory.com/mcp/fetchMessages?space=preferences&limit=20" \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY"

# Python
response = requests.get(
    f"{BASE_URL}/mcp/fetchMessages",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"space": "preferences", "limit": 20},
)
memories = response.json()["memories"]

# TypeScript
const response = await fetch(
  `${BASE_URL}/mcp/fetchMessages?space=preferences&limit=20`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { memories } = await response.json();

Delete a Memory

Remove a specific memory by its ID. This is permanent and cannot be undone.

# curl — delete a space
curl -X DELETE https://backend.persistmemory.com/spaces/my-space-id \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY"

# Python
requests.delete(
    f"{BASE_URL}/spaces/my-space-id",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

# TypeScript
await fetch(`${BASE_URL}/spaces/my-space-id`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` },
});

Using Memory Spaces

Spaces are namespaces that isolate groups of memories. Each space has its own vector index, so memories in one space are completely invisible to searches in another. Use spaces to separate projects, environments, or user contexts.

# Store to different spaces
curl -X POST https://backend.persistmemory.com/mcp/addMemory \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"space": "project-alpha", "title": "CI/CD", "text": "Deploy pipeline uses GitHub Actions"}'

curl -X POST https://backend.persistmemory.com/mcp/addMemory \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"space": "project-beta", "title": "CI/CD", "text": "Deploy pipeline uses GitLab CI"}'

# Searching project-alpha only returns GitHub Actions memory
curl -X POST https://backend.persistmemory.com/mcp/search \
  -H "Authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"space": "project-alpha", "q": "deployment pipeline", "top_k": 5}'

Spaces are created automatically the first time you store a memory with a new space name. There is no setup step or limit on the number of spaces. If you omit the space parameter, memories go into the default space.

Using Metadata

Attach structured metadata to memories for filtering and organization. Metadata is a free-form JSON object — you can store any key-value pairs that make sense for your application.

# Python example — store a memory with descriptive title
requests.post(
    f"{BASE_URL}/mcp/addMemory",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "space": "support-tickets",
        "title": "Safari 17 login failure — SameSite cookie fix",
        "text": "Customer reported login failures on Safari 17. "
                "Root cause was SameSite cookie policy change. "
                "Ticket SUP-4521, severity high, resolved. "
                "Tags: auth, cookies, safari.",
    },
)

Metadata is returned with every memory in search and list responses, making it easy to filter results in your application code after retrieval. Common metadata fields include type, source, tags, and confidence.

Rate Limits and Best Practices

Keep these guidelines in mind as you build with the API:

  • Batch similar memories. Instead of storing every sentence separately, combine related observations into a single memory with 2-3 sentences. This improves search quality and reduces API calls.
  • Avoid exact duplicates. Search before storing to check if a similar memory already exists. If the search returns a score above 0.95, the information is likely already stored.
  • Use descriptive content. Memories like "yes" or "done" are not useful for semantic search. Write complete sentences that capture the full context of the information.
  • Keep spaces focused. A space with thousands of unrelated memories will have lower search precision than several focused spaces with hundreds of related memories each.
  • Handle rate limits gracefully. If you receive a 429 response, back off and retry after the delay indicated in the Retry-After header.

Related Resources

Python Agent Tutorial

Build a complete AI agent with persistent memory using this API.

MCP for Claude Desktop

Use MCP instead of REST for seamless Claude Desktop integration.

Full Documentation

Complete API reference with all endpoints, parameters, and response schemas.

AI Agent Memory

Learn about memory architectures and patterns for production AI agents.

Start Using the API

Create a free account, grab your API key, and start storing memories in under a minute.

Get Your API KeyWhy Persistent Memory?