Quickstart: API

This guide walks through the core operations using curl.

Prerequisites

• Installation completed
• memlayer server running (bb local-server or bb server)

Step 1: Store a memory (retain)

curl -X POST http://localhost:8090/api/v1/retain \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers Neovim as their primary editor", "source": "conversation"}'

Example response:

{
  "operations": [
    {
      "type": "create",
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "User prefers Neovim as their primary editor",
      "reason": "New fact about user editor preference"
    }
  ],
  "summary_triggered": false
}

The retain pipeline extracts entities from the input, decides whether to create or update, generates a vector embedding, and stores everything in Datahike and the Proximum vector index.

Step 2: Search memories (recall)

curl -X POST http://localhost:8090/api/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "editor preference", "limit": 5}'

Example response:

{
  "query": "editor preference",
  "answer": "The user prefers Neovim as their primary editor.",
  "memories": [
    {
      "memory-id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "User prefers Neovim as their primary editor",
      "layer": "fact",
      "importance": 0.75,
      "distance": 0.42
    }
  ],
  "count": 1
}

Recall converts the query into a vector embedding and performs a semantic search. Results are ranked by distance (lower = more similar).

Step 3: Consolidate memories (reflect)

curl -X POST http://localhost:8090/api/v1/reflect \
  -H "Content-Type: application/json" \
  -d '{}'

Reflect scans your stored memories and groups related facts into higher-level concepts and domains.

Step 4: Forget a memory

Use the memory-id from a recall response to remove a specific memory:

curl -X POST http://localhost:8090/api/v1/forget \
  -H "Content-Type: application/json" \
  -d '{"memory-id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Forget removes the memory from active queries and deletes its embedding. Datahike retains the historical record for audit purposes, but the memory will no longer appear in recall results.

Next steps

• Concepts — understand semantic layers, temporal queries, and the knowledge graph
• API Reference — full endpoint documentation with request/response schemas
• MCP Integration — use MemLayer as a tool in Claude Desktop or Claude Code