REST API - MemMachine Documentation

Hello World: A Guide to the MemMachine RESTful API v2

This guide provides a quick and simple way to get started with the MemMachine RESTful API v2 using curl commands.

Prerequisites

Ensure your MemMachine server is running.

memmachine-server

List Projects

Check for existing projects. This POST request returns a list of all projects available in your organization.Command:

curl -X POST "http://127.0.0.1:8080/api/v2/projects/list" \
-H "Content-Type: application/json" \
-d '{}'

Create a Project

Before adding memories, you must ensure a project exists.Command:

curl -X POST "http://127.0.0.1:8080/api/v2/projects" \
-H "Content-Type: application/json" \
-d '{
  "org_id": "my-org",
  "project_id": "my-first-project",
  "description": "A test project for REST API",
  "config": {
    "embedder": "my-openai-embedder",
    "reranker": "my-rrf-reranker"
  }
}'

Add a New Memory

The POST /api/v2/memories endpoint allows you to add one or more messages to the system.Command:

curl -X POST "http://127.0.0.1:8080/api/v2/memories" \
-H "Content-Type: application/json" \
-d '{
  "org_id": "my-org",
  "project_id": "my-first-project",
  "messages": [
    {
      "content": "This is a simple test memory.",
      "producer": "user-alice",
      "produced_for": "agent-bob",
      "role": "user",
      "timestamp": "2025-11-24T10:00:00Z",
      "metadata": {
        "type": "fact",
        "topic": "testing"
      }
    }
  ]
}'

Expected Output:You will receive a JSON response containing the results of the operation.

Search for the Memory

Now let’s find the memory we just added. The POST /api/v2/memories/search endpoint searches both episodic and semantic memory. Set agent_mode to true to use retrieval-agent search behavior.Command:

curl -X POST "http://127.0.0.1:8080/api/v2/memories/search" \
-H "Content-Type: application/json" \
-d '{
  "org_id": "my-org",
  "project_id": "my-first-project",
  "query": "simple test memory",
  "top_k": 5,
  "types": ["episodic", "semantic"],
  "agent_mode": true
}'

Expected Output:You should see a JSON response containing episodic_memory and semantic_memory results that match your query.

Delete Memories

To clean up, you can use the POST /api/v2/memories/episodic/delete endpoint to remove specific chronological events or message logs.Command:

curl -X POST "[http://127.0.0.1:8080/api/v2/memories/episodic/delete](http://127.0.0.1:8080/api/v2/memories/episodic/delete)" \
-H "Content-Type: application/json" \
-d '{
  "org_id": "my-org",
  "project_id": "my-first-project",
  "episodic_id": "specific-id-here",
  "episodic_ids": []
}'

You will also want to use the POST /api/v2/memories/semantic/delete endpoint to remove distilled facts, traits, or knowledge entries:

curl -X POST "[http://127.0.0.1:8080/api/v2/memories/semantic/delete](http://127.0.0.1:8080/api/v2/memories/semantic/delete)" \
-H "Content-Type: application/json" \
-d '{
  "org_id": "my-org",
  "project_id": "my-first-project",
  "semantic_id": "specific-id-here",
  "semantic_ids": []
}'
</Step> </Steps>
    "producer": "user-alice"
  }
}'

​Hello World: A Guide to the MemMachine RESTful API v2

​Prerequisites

Hello World: A Guide to the MemMachine RESTful API v2

Prerequisites