REST API

Legacy FastAPI HTTP interface for remote access and service integration.

Legacy Interface

The REST API server is a legacy FastAPI application embedded in mnemosyne/cli.py. It is not part of the BEAM architecture. For new integrations, prefer the Python SDK or Hermes plugin.

Starting the Server

python -m mnemosyne   --host 0.0.0.0   --port 8090   --db-path ./memory.db

Or via Docker:

docker run -p 8090:8090   -v $(pwd)/memory.db:/data/memory.db   mnemosyne/server:latest

Endpoints

Status

GET /

# Response:
{
"status": "ok",
"version": "2.8.0",
"working_count": 42,
"episodic_count": 128,
"semantic_count": 64
}

Store Memory

POST /store
Content-Type: application/json

{
"content": "User prefers dark mode.",
"tags": ["preferences", "ui"],
"importance": 0.8,
"source": "conversation"
}

# Response:
{
"id": "mem_abc123",
"status": "stored"
}

Recall (Search)

GET /recall?query=user+preferences&top_k=5

# Response:
{
"results": [
  {
    "id": "mem_abc123",
    "content": "User prefers dark mode.",
    "score": 0.95,
    "tags": ["preferences", "ui"]
  }
],
"total": 1
}

Session Context

GET /session/{session_id}

# Response:
{
"session_id": "sess_123",
"memories": [
  {
    "id": "mem_abc123",
    "content": "User prefers dark mode.",
    "tags": ["preferences", "ui"],
    "importance": 0.8,
    "created_at": "2026-04-25T14:30:00Z"
  }
],
"total": 1
}

Statistics

GET /stats

# Response:
{
"working_count": 42,
"episodic_count": 128,
"semantic_count": 64,
"db_size_mb": 12.5,
"last_sleep_at": "2026-04-25T13:00:00Z"
}

Forget (Delete Memory)

DELETE /forget/{memory_id}

# Response:
{
"status": "forgotten",
"id": "mem_abc123"
}

Update Memory

PUT /update/{memory_id}
Content-Type: application/json

{
"content": "User prefers dark mode and large fonts.",
"importance": 0.9
}

Consolidate

POST /consolidate

# Response:
{
"status": "consolidated",
"consolidated_count": 15,
"evicted_count": 3
}

Error Responses

Status	Code	Description
400	`INVALID_REQUEST`	Malformed request body
404	`NOT_FOUND`	Memory not found
500	`INTERNAL_ERROR`	Server error

OpenAPI Spec

The server exposes OpenAPI documentation at:

Swagger UI: http://localhost:8090/docs
ReDoc: http://localhost:8090/redoc
OpenAPI JSON: http://localhost:8090/openapi.json

CORS

The REST server enables CORS by default for all origins in development. In production, configure allowed origins via MNEMOSYNE_CORS_ORIGINS.

API Overview

Overview of all Mnemosyne API interfaces: Python SDK, REST API, Hermes plugin, and tool schema. Choo...

Python SDK

Complete reference for the Mnemosyne Python SDK: Memory class, store/query/delete operations, config...

Deployment Overview

Overview of Mnemosyne deployment options: Docker, Fly.io, systemd services, and cron jobs. Choose th...