← Back to API


OpenMemo API Documentation

The Memory Architecture for AI Systems — REST API Reference

Base URL
https://api.openmemo.ai

Health Check

GET /health Check if the API is running

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

Request
curl https://api.openmemo.ai/health
Response 200
{
  "status": "ok",
  "service": "openmemo",
  "version": "0.1.0"
}

Add Memory

POST /api/memories Store a new memory

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.

Request Body
Parameter Type Required Description
content string required The memory content to store
source string optional Source identifier. Default: "api"
metadata object optional Additional key-value metadata
Request
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"}
  }'
Response 201
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Error 400
{
  "error": "content is required"
}

Recall Memory

POST /api/memories/recall Search and retrieve memories

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

Request Body
Parameter Type Required Description
query string required The search query
top_k integer optional Maximum results to return. Default: 10
budget integer optional Token budget for context. Default: 2000
Request
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}'
Response 200
{
  "results": [
    {
      "content": "User prefers PostgreSQL for production",
      "score": 3.576,
      "source": "fast",
      "cell_id": "c81adb48-9c52-460d-af69-d3c0993210d4"
    }
  ]
}

Reconstruct Memory

POST /api/memories/reconstruct Rebuild a coherent narrative from memories

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

Request Body
Parameter Type Required Description
query string required The topic to reconstruct
max_sources integer optional Maximum source memories to use. Default: 10
Request
curl -X POST https://api.openmemo.ai/api/memories/reconstruct \
  -H "Content-Type: application/json" \
  -d '{"query": "What happened with the database setup?"}'
Response 200
{
  "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
}

Maintenance

POST /api/maintain Run memory maintenance tasks

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

Request
curl -X POST https://api.openmemo.ai/api/maintain
Response 200
{
  "pyramid": {
    "promoted": 3,
    "compressed": 12
  },
  "new_skills": 1,
  "total_cells": 42
}

Statistics

GET /api/stats Get memory system statistics

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

Request
curl https://api.openmemo.ai/api/stats
Response 200
{
  "notes": 42,
  "cells": 42,
  "scenes": 3,
  "skills": 5,
  "stages": {
    "exploration": 30,
    "active": 10,
    "consolidated": 2
  },
  "unresolved_conflicts": 0
}

Python SDK

SDK pip install openmemo Use OpenMemo directly in Python

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

Install
pip install openmemo
Usage
# 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"])
With vector search
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

Error Handling

All endpoints return JSON error responses with an error field.

Status Code Meaning
200 Success
201 Created (new memory added)
400 Bad request (missing required fields)
500 Internal server error
Error response format
{
  "error": "content is required"
}