API Reference

Base URL: https://memento-api.myrakrusemark.workers.dev

Authentication

All /v1/* endpoints require an API key:

Authorization: Bearer mp_live_your_key_here

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer mp_live_...`
`X-Memento-Workspace`	No	Workspace name (default: `"default"`)
`Content-Type`	POST/PUT	`application/json`

Context

POST /v1/context

Single retrieval — everything relevant for a message. See Context Endpoint for full details.

Memories

POST /v1/memories

Store a new memory.

{
  "content": "The user prefers dark mode.",
  "type": "instruction",         // fact | decision | observation | instruction
  "tags": ["preferences"],       // optional
  "expires": "2026-06-01",       // optional ISO date
  "linkages": [                  // optional
    { "type": "memory", "id": "abc123", "label": "related" }
  ]
}

Returns 201 with the memory ID.

GET /v1/memories

List/browse memories with pagination and filtering.

Param	Default	Description
`type`	—	Filter by type
`tags`	—	Comma-separated tags (OR match)
`status`	`active`	`active` \| `consolidated` \| `expired` \| `all`
`sort`	`created_at`	`created_at` \| `relevance` \| `access_count`
`order`	`desc`	`asc` \| `desc`
`limit`	`50`	1–100
`offset`	`0`	Pagination offset

Returns { memories, total, offset, limit }.

POST /v1/memories/ingest

Bulk store up to 100 memories at once.

{
  "memories": [
    { "content": "...", "type": "fact", "tags": ["import"] },
    { "content": "...", "type": "observation" }
  ],
  "source": "migration"  // optional, added as tag
}

GET /v1/memories/:id

Get a single memory by ID.

PUT /v1/memories/:id

Partial update — any subset of content, type, tags, expires, linkages.

DELETE /v1/memories/:id

Delete a memory, its access logs, and vector embedding.

GET /v1/memories/:id/graph?depth=2

BFS subgraph traversal through linkages. Max depth: 5. Returns { nodes, edges }.

GET /v1/memories/:id/related

Direct connections only — outgoing linkages and reverse links. Returns { outgoing, incoming }.

Working Memory

GET /v1/working-memory

Full working memory document (all sections as markdown).

GET /v1/working-memory/:section

Single section content.

PUT /v1/working-memory/:section

Update section content. Body: { "content": "..." }.

Working Memory Items

POST /v1/working-memory/items

Create a structured item.

{
  "category": "active_work",
  "title": "Build semantic search",
  "content": "Embed memories using bge-small-en-v1.5...",
  "priority": 8,
  "tags": ["memento", "search"],
  "next_action": "Write the hybrid ranking function"
}

GET /v1/working-memory/items

List items. Filterable by category and status.

GET /v1/working-memory/items/:id

Get single item.

PUT /v1/working-memory/items/:id

Update item — any subset of fields.

DELETE /v1/working-memory/items/:id

Delete item.

Skip List

POST /v1/skip-list

Add a skip entry. Body: { "item": "...", "reason": "...", "expires": "..." }.

GET /v1/skip-list/check?query=...

Check a message against the skip list. Returns matches.

DELETE /v1/skip-list/:id

Remove a skip entry.

Distillation

POST /v1/distill

Extract memories from a conversation transcript using LLM. Sends the transcript to Llama 3.1 8B along with existing memories for deduplication, parses the response, and stores novel memories with a source:distill tag.

{
  "transcript": "[Human]: We decided to use KV for contact form storage.
[Agent]: The worker stores them with msg: prefix keys."
}

Behavior	Description
Min length	Transcript must be ≥ 200 chars (skips trivial conversations)
Max length	Transcript capped at 100K chars before sending to LLM
Dedup	Fetches 200 most recent active memories as context for the LLM
Per-call cap	Max 20 memories extracted per distillation
Tagging	Every distilled memory gets `source:distill` added to its tags
Embeddings	Each memory is embedded (fire-and-forget) for semantic search

Returns 201 with list of stored memories, or 200 if nothing novel found. Returns 503 if AI binding unavailable, 502 on AI failure.

Consolidation

POST /v1/consolidate

Run automatic consolidation — groups related memories by tag overlap, generates AI or template summaries.

POST /v1/consolidate/group

Consolidate specific memory IDs on demand.

{
  "memory_ids": ["abc123", "def456", "ghi789"],
  "summary": "Optional custom summary"
}

Identity

GET /v1/identity

Current identity crystal.

PUT /v1/identity

Store identity crystal manually. Body: { "crystal": "..." }.

POST /v1/identity/crystallize

Auto-generate crystal from working memory, top memories, and consolidation summaries.

GET /v1/identity/history

Past crystal snapshots.

Health & Admin

GET /v1/health

Workspace health stats — memory counts, working memory staleness, skip list count, access log totals.

POST /v1/admin/backfill-embeddings

Embed all un-embedded memories. Processes in batches of 50. Idempotent.

Workspaces

POST /v1/workspaces

Create workspace. Body: { "name": "my-project" }.

GET /v1/workspaces

List all workspaces.

DELETE /v1/workspaces/:id

Delete workspace and its database.