Writing your own client

Everything above is done through MCP tools. If you are writing your own client or integration, this is what it picks from.

MCP tools

tool	what it does
mnemos_observe	write an event
mnemos_fact_add	write facts in one batch
mnemos_recall	retrieval by meaning: facts, events, instructions, pins
mnemos_facts	everything about one entity, history, audit sweeps
mnemos_episodes	search and browse events, body by id
mnemos_routes	links between entities, in both directions
mnemos_entity_search	search and browse entities
mnemos_entity_save	create entities
mnemos_entity_edit	update, merge, delete, graph centre, unreachability
mnemos_fact_edit	close, reword, redate, repoint, merge, mark used
mnemos_episode_edit	move, declare factless, attach files, delete
mnemos_skill, mnemos_skill_save, mnemos_skill_edit	instructions
mnemos_todo_list, mnemos_todo_edit	todos
mnemos_pin_list, mnemos_pin_edit	pinned notes
mnemos_context, mnemos_context_save, mnemos_context_edit	handing a conversation over
mnemos_state_get, mnemos_state_set	bookmarks for recurring jobs
mnemos_scopes, mnemos_scope_describe, mnemos_scope_share	areas and access

Each schema arrives with tools/list together with its description — including the predicate list, the date formats and which fields are required.

The schema is the contract: the server validates arguments against it and refuses an unknown parameter by name, listing what it does accept.

HTTP/JSON

The same set of operations is available over HTTP under the same token:

curl -H "Authorization: Bearer $TOKEN" \
     https://mnemos.example.com/api/scopes

The OpenAPI document is at /openapi.yaml and is what a typed client is generated from. Every operation with its request body is in the reference.

A 401 means the route is there and the token was refused, 402 that the account has no entitlement to mnemos, 404 that the request never reached the server.

Worth knowing up front

A write is two calls. mnemos_observe first — it returns the event's id — then mnemos_fact_add referring to it. All facts in one call: the shared work is done once per batch.

The ends of a fact are ids, not names. An id is eight hex characters, a1b2c3d4; mnemos_entity_search returns them and mnemos_entity_save creates what does not exist yet.

A retrieval query is an array of concepts, not a question in a sentence. Each gets its own search and the results merge round-robin.

Dates go through one reader: 2026-08-20, 2026-08-20 14:30, the T form and RFC3339. With no zone given, UTC. A phrase like "yesterday" is refused.