Memories

POST /api/v1/retain

Ingest content into the knowledge graph.

curl -X POST https://api.memlayer.dev/api/v1/retain \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers Haskell for type-safe programming", "source": "conversation"}'

Request:

Field	Type	Required	Description
`content`	string	Yes	Content to process and extract memories from
`source`	string	No	Origin identifier
`system`	string	No	System context for LLM
`valid_time`	ISO 8601	No	When this fact was true (defaults to now)

Response:

{
  "operations": [
    {
      "type": "create",
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": "User prefers Haskell for type-safe programming",
      "reason": "New fact about programming preference"
    }
  ],
  "summary_triggered": false,
  "usage": {
    "extraction": {"prompt_tokens": 150, "completion_tokens": 50, "total_tokens": 200},
    "decision": {"prompt_tokens": 200, "completion_tokens": 30, "total_tokens": 230},
    "total_tokens": 430
  }
}

GET /api/v1/recall

Semantic search for memories.

curl "https://api.memlayer.dev/api/v1/recall?query=programming+language&limit=5&expand_graph=true"

Query Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search
`limit`	int	No	Max results (default: 5)
`layer`	int (0-3)	No	Filter by semantic layer
`as_of`	ISO 8601	No	Temporal query point
`expand_graph`	bool	No	Include relationships and ancestors

Response:

{
  "memories": [
    {
      "memory": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "entity_id": "user-haskell-preference",
        "content": "User prefers Haskell for type-safe programming",
        "layer": 2,
        "importance": 0.75,
        "valid_from": "2025-01-15T10:30:00Z",
        "valid_to": null
      },
      "similarity_score": 0.92,
      "relationships": [],
      "ancestors": []
    }
  ],
  "usage": {"prompt_tokens": 50, "completion_tokens": 0, "total_tokens": 50}
}

POST /api/v1/reflect

Consolidate and organize memories.

curl -X POST https://api.memlayer.dev/api/v1/reflect \
  -H "Content-Type: application/json" \
  -d '{"query": "programming", "dry_run": false}'

Request:

Field	Type	Required	Default	Description
`query`	string	No	—	Topic filter
`dry_run`	bool	No	false	Preview without applying
`threshold`	float	No	0.7	Linking threshold
`cluster_threshold`	float	No	0.8	Clustering threshold
`limit`	int	No	100	Max facts to process

POST /api/v1/forget

Delete an entity and all its data from active queries.

curl -X POST https://api.memlayer.dev/api/v1/forget \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "user-haskell-preference"}'

Response:

{
  "entity_id": "user-haskell-preference",
  "memories_removed": 1,
  "relationships_removed": 2
}

POST /api/v1/ingest

Bulk memory ingestion without LLM processing.

curl -X POST https://api.memlayer.dev/api/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"content": "Alice is a software engineer", "source": "import"},
      {"content": "Alice lives in Berlin", "source": "import"}
    ],
    "entity_id": "alice-profile"
  }'

Response:

{"processed": 2, "failed": 0, "results": [{"success": true, "memory_id": "uuid-1"}, {"success": true, "memory_id": "uuid-2"}]}

GET /api/v1/memories

List memories with optional filters.

curl "https://api.memlayer.dev/api/v1/memories?entity_id=alice-profile&layer=2&limit=20"

Parameter	Type	Description
`entity_id`	string	Filter by entity
`layer`	string	Filter by layer
`limit`	int	Max results

GET /api/v1/memories/:id

Get a single memory by UUID. Returns 404 if not found.

curl https://api.memlayer.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890

DELETE /api/v1/memories/:id

Delete a single memory. Returns 204 No Content.

curl -X DELETE https://api.memlayer.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890

GET /api/v1/memories/:id/children

Get child memories in the layer hierarchy.

curl https://api.memlayer.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/children

GET /api/v1/memories/:id/relationships

Get all relationships where this memory is source or target.

curl https://api.memlayer.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships

GET /api/v1/memories/:id/layer/:layer

Traverse to a specific layer from a given memory.

curl https://api.memlayer.dev/api/v1/memories/a1b2c3d4-e5f6-7890-abcd-ef1234567890/layer/0

Returns ancestors or descendants at the requested layer.