OpenMemo API Documentation

Returns the service status and version. Use this to verify connectivity.

curl https://api.openmemo.ai/health

{
  "status": "ok",
  "service": "openmemo",
  "version": "0.1.0"
}

Add a piece of information to OpenMemo. The system automatically creates a structured MemCell, detects conflicts with existing memories, and indexes the content for recall.

curl -X POST https://api.openmemo.ai/api/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers PostgreSQL for production",
    "source": "config",
    "metadata": {"project": "myapp"}
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "error": "content is required"
}

Recall relevant memories using OpenMemo's tri-brain search engine. Combines BM25 lexical matching with optional vector similarity for accurate retrieval.

curl -X POST https://api.openmemo.ai/api/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "What database does the user prefer?", "top_k": 5}'

{
  "results": [
    {
      "content": "User prefers PostgreSQL for production",
      "score": 3.576,
      "source": "fast",
      "cell_id": "c81adb48-9c52-460d-af69-d3c0993210d4"
    }
  ]
}

Instead of returning raw memory chunks, OpenMemo reconstructs a coherent narrative from related memories. This resolves conflicts and builds a timeline of events.

curl -X POST https://api.openmemo.ai/api/memories/reconstruct \
  -H "Content-Type: application/json" \
  -d '{"query": "What happened with the database setup?"}'

{
  "query": "What happened with the database setup?",
  "narrative": "- User prefers PostgreSQL for production\n- Database set to port 5432",
  "sources": ["a1b2...", "c3d4..."],
  "confidence": 0.85
}

Triggers the Memory Pyramid compression, skill extraction, and governance cleanup. Run periodically to keep memory healthy and reduce noise.

curl -X POST https://api.openmemo.ai/api/maintain

{
  "pyramid": {
    "promoted": 3,
    "compressed": 12
  },
  "new_skills": 1,
  "total_cells": 42
}

Returns current statistics about the memory system, including counts for notes, cells, scenes, skills, and lifecycle stages.

curl https://api.openmemo.ai/api/stats

{
  "notes": 42,
  "cells": 42,
  "scenes": 3,
  "skills": 5,
  "stages": {
    "exploration": 30,
    "active": 10,
    "consolidated": 2
  },
  "unresolved_conflicts": 0
}

For local usage without a server, install the Python SDK and use OpenMemo directly in your code.

pip install openmemo

# Basic usage
from openmemo import Memory

memory = Memory()

memory.add("User prefers dark mode")
memory.add("User changed preference to light mode")

results = memory.recall("What theme does the user prefer?")
for r in results:
    print(r["content"], r["score"])

from openmemo import Memory

def my_embed(text):
    return model.encode(text).tolist()

memory = Memory(embed_fn=my_embed)
memory.add("User prefers dark mode")
results = memory.recall("UI preference")  # BM25 + vector

All endpoints return JSON error responses with an error field.

{
  "error": "content is required"
}