API reference
Every Mnemosyne instance serves its own OpenAPI 3.1 document at:
GET http://your-instance:3000/v1/openapi.jsonThis page summarises the surface. The server also ships a built-in
Scalar reference UI at /v1/docs. For raw bytes you
can pipe into a generator, hit the URL above. The API exposes ~130
endpoints across 40 route modules.
Authentication
Every request needs a single header:
Authorization: Bearer mns_live_xxxThe workspace is derived from the API key — there is no separate workspace
header. API keys are created with the CLI or the management endpoint.
Workspaces are isolated at the database level via PostgreSQL Row-Level
Security with FORCE, so a leaked key for workspace A cannot read
workspace B even if the application code is wrong.
Resource families
| Resource | Base path | What lives here |
|---|---|---|
| Recall | POST /v1/recall | The single most important endpoint. Hybrid retrieval. |
| Facts | /v1/facts | Create / read / patch / pin / forget / restore |
| Decisions | /v1/decisions | Policy/choice with rationale + supersession chain |
| Episodes | /v1/episodes | Temporal event with linked facts |
| Entities | /v1/entities | Canonical things, graph edges, drawer membership |
| Relations | /v1/relations | 9 locked verbs between primitives |
| Graph | GET /v1/graph | Subgraph for visualisation |
| Timeline | GET /v1/timeline | Time-ordered episodes and events |
| Citations | /v1/facts/:id/citations | Source message ids that produced a fact |
| Review | /v1/review | Conflict queue for human-in-the-loop resolution |
| Export | /v1/export | Stream the workspace as JSONL (portability, backups) |
| Audit | /v1/audit | Append-only operation log |
| Health | GET /v1/health | Live snapshot of the workspace vitals |
Idempotency
Mutating endpoints accept an optional Idempotency-Key header. Identical
keys within a 24h window return the cached response — useful for retries
in unreliable networks.
Errors
Every error has a stable code and a human-readable message. The full
mapping lives at Error codes.
The OpenAPI is the source of truth. Every SDK in packages/client-*
is generated from it. Every example in this site is a real test that
runs in CI against the generated client. If the API drifts, the build
breaks.