API Reference

Learn how to integrate with Spomory's six memory tools.

Authentication

Local — the MCP server talks to your client over stdio. No auth: the trust boundary is whoever can start the process.

Cloud — two schemes, same six tools

x-api-key header, for clients that can't do OAuth (Cursor, Doubao, ModelScope's marketplace, mcp-remote) — connect to https://api.yliuai.com/mcp-apikey/. OAuth 2.1 + PKCE, required by Anthropic's Connector Directory — connect to https://api.yliuai.com/mcp. Both mounts share the same tool logic and resolve to the same per-user memory graph.

Responses & errors

Every tool and REST endpoint shares the same two outcomes, straight from the live OpenAPI spec at api.yliuai.com/openapi.json — there's no 400/401/404/500 to document here because the deployed API doesn't define one.

Success

Every REST endpoint returns the same envelope, whatever the underlying tool returned:

{"result": "<string>"}

Validation error — HTTP 422

A missing or malformed parameter returns FastAPI's standard validation-error shape:

{
  "detail": [
    {
      "loc": ["query", "query"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Tools

Write

add_memory

Sends text through an LLM that extracts it into (subject, predicate, object) triples and writes them into the memory graph.

Param	Type	Default	Description
`text`	`string`	required	The text to extract memories from.
`source_id`	`string`	`"mcp-session"`	Tag identifying where this text came from.

Returns: A one-line summary, e.g. "2 new entities, 1 merged, 3 new relations."

Read

search_memory

Matches query against extracted triples, then runs personalized PageRank over the memory graph to assemble a natural-language context.

Param	Type	Default	Description
`query`	`string`	required	What to search for.
`top_k`	`number`	`10`	Maximum number of matching facts to seed the search with.

Returns: The assembled context, or "No matching memory found." if nothing matched.

Not strictly read-only — it also bumps the last-retrieved timestamp on whichever facts it surfaces, feeding the staleness-aware ranking.

get_graph Read-only

Returns the subgraph within hops hops of entity_name.

Param	Type	Default	Description
`entity_name`	`string`	required	The entity to center the subgraph on.
`hops`	`number`	`1`	How many relation hops to include.

Returns: {entities, relations} as JSON, or {} if no entity matched.

export_memory Read-only

Exports the full memory graph as a memory-passport JSON document.

Param	Type	Default	Description
`subject_id`	`string`	`"default"`	Which memory graph to export.

Returns: The passport JSON.

Delete

forget_memory Destructive

Finds the single fact that best matches query and permanently deletes it — one relation per call, by design, so a vague query that could match many facts has to be narrowed and retried instead of silently deleting the wrong ones.

Param	Type	Default	Description
`query`	`string`	required	Identifies the single fact to delete.

Returns: "Forgot: subject–predicate–object", or a message if the memory graph is empty.

forget_all_memory Destructive

Permanently deletes the entire memory graph in one call — every entity, relation, and archived history version. forget_memory is deliberately one-fact-at-a-time; this is its bulk counterpart, added after a real user had to call forget_memory four times in a row (each gated behind a client approval prompt) just to clear four stored facts. Two-step by design: a call left at confirm=false deletes nothing, it only reports what a real call would remove — destructive_hint is only a hint the MCP spec doesn't require a host to enforce, so confirm is the actual safeguard against a host (or an auto-approving agent) that treats it as cosmetic.

Param	Type	Default	Description
`confirm`	`boolean`	`false`	Must be true to actually delete; false only previews the count.

Returns: Left at confirm=false: a report of how many entities/relations a real call would delete. With confirm=true: a summary of how many were actually deleted, or a message if the memory graph was already empty.

Full source: memory_core/mcp_server/server.py on GitHub →

REST API

The same six tools, over plain HTTP instead of MCP — for n8n, Zapier, or any script that can make a request. Base URL https://api.yliuai.com. Auth is the same x-api-key header or Authorization: Bearer <key> as the cloud MCP endpoint — get a key on the Cloud & Apps page.

Example — add_memory over curl:

curl -X POST https://api.yliuai.com/v1/memories \
  -H "x-api-key: <your key>" \
  -H "Content-Type: application/json" \
  -d '{"text": "I work as a backend engineer at Some Company."}'

Write

POST /v1/memories

REST equivalent of add_memory.

Param	In	Type	Default	Description
`text`	body	`string`	required	The text to extract memories from.
`source_id`	body	`string`	`"api"`	Tag identifying where this text came from.

Returns: {"result": "2 new entities, 1 merged, 3 new relations."}

Read

GET /v1/memories/search

REST equivalent of search_memory.

Param	In	Type	Default	Description
`query`	query	`string`	required	What to search for.
`top_k`	query	`number`	`10`	Maximum number of matching facts to seed the search with.

Returns: {"result": "<assembled context, or \"No matching memory found.\">"}

GET /v1/graph Read-only

REST equivalent of get_graph.

Param	In	Type	Default	Description
`entity_name`	query	`string`	required	The entity to center the subgraph on.
`hops`	query	`number`	`1`	How many relation hops to include.

Returns: {"result": "{\"entities\": [...], \"relations\": [...]}"}

GET /v1/export Read-only

REST equivalent of export_memory.

Param	In	Type	Default	Description
`subject_id`	query	`string`	`"default"`	Which memory graph to export.

Returns: {"result": "<passport JSON, as a string>"}

Delete

POST /v1/memories/forget Destructive

REST equivalent of forget_memory — deletes the single best-matching fact.

Param	In	Type	Default	Description
`query`	body	`string`	required	Identifies the single fact to delete.

Returns: {"result": "Forgot: subject–predicate–object"}

POST /v1/memories/forget-all Destructive

REST equivalent of forget_all_memory. Same two-step safeguard: confirm=false (the default) deletes nothing and only reports what a real call would remove.

Param	In	Type	Default	Description
`confirm`	query	`boolean`	`false`	Must be true to actually delete; false only previews the count.

Returns: {"result": "<counts that would be / were deleted>"}

Full OpenAPI spec (for tools that auto-import it) →