Building with MemorySync

This skill is the decision-and-workflow layer for building on MemorySync: how to reason about the platform, scope projects and end users, ingest, retrieve, and evaluate whether it delivers your use case. It is not an API reference — for exact, current details (endpoints, parameters, fields, limits) query the memorysync-docs MCP server first. If this skill and the live documentation ever disagree, the live docs win.

Source authority — read before you write code

The memorysync-docs MCP server (https://docs.memorysync.io/mcp, no auth) is the ground truth. Use it in this order:

1. list_doc_sections (no arguments) — orient: the top-level sections and page counts.
2. search_docs (query, optional limit 1–20) — discover which page covers your feature. Results include a markdown_url for each page.
3. read_doc (path, e.g. /quickstart or /api/memory/add) — load the WHOLE page. Prefer a full page over search snippets whenever you need exact method names, parameters, fields, or limits.

The server also exposes the implement_with_memorysync prompt (arguments: task, optional language) which runs this search-then-read loop for you, and a docs-index resource (the curated llms.txt).

No MCP available? Fetch https://docs.memorysync.io/llms.txt for the page index and read the Markdown twins it links. Never invent an endpoint or parameter from memory.

The mental model (stable)

MemorySync stores memory on two planes:

• Verbatim turns (episodic): exact conversation exchanges, written with content-hash idempotency seeds so replays and multi-surface writes converge on one stored row. Nothing is paraphrased at write time.
• Distilled facts: the platform extracts, deduplicates, updates, and ranks durable facts server-side. You store honestly; intelligence happens after.

Retrieval reads both planes. You never choose between "raw" and "smart" storage — you get both from the same writes.

1. Scope: projects and end users

Isolation is enforced by request headers, not by filter arguments a bug can forget:

• X-API-Key — authenticates the org (tenant).
• X-End-User-ID — REQUIRED scoping for every read and write on the dashboard-key surface. One value per human user of YOUR product. A read can never be widened by a missing filter, because the server scopes it.
• X-Project-ID — optional: one org key serving several projects. Omit it for single-project apps (the default project applies).

Decision rules:

• Per-user memory (assistants, copilots, support): X-End-User-ID = your stable user id. Never an email (PII in an id), never a session id (memory would not persist).
• Shared/team memory (one knowledge pool): a fixed logical id such as team — deliberate, documented, and still header-scoped.
• Multi-app products: same end-user id across your apps = one memory that follows the user; different ids = isolated memories. Choose deliberately.

2. Ingest

Three write paths — pick by shape, confirm details via read_doc:

• POST /memory/add — one durable fact or document snippet ({"text": ...}, optional tags, importance, metadata). Use for explicit "remember this" material.
• POST /v1/memory/add_turn — one verbatim conversation turn. Body carries tenant_id, user_id, source, text ("human: ..." / "ai: ..."), a speaker seed, and metadata.session_id. Give every turn a deterministic content-hash seed (the docs and every official adapter use FNV-1a 64 over the text) so retries can never double-store.
• POST /memory/bulk-add — batches. It answers 207 with per-item outcomes: read results[] — a batch is routinely part-success, and the status code alone tells you nothing about any given record.

Invariants:

• Never store secrets — API keys, passwords, tokens. Refuse them client-side before any network call, whatever the model asks.
• Store one clear, self-contained statement per fact, not chat noise.

3. Retrieve

• POST /memory/query — semantic search ({"query": ..., "k": ...}) on the dashboard surface with X-End-User-ID. The workhorse.
• POST /v1/memory/recall — hierarchical recall for prompt injection: returns a ready context string. When it answers empty for verbatim-turn content, fall back to POST /v1/memory/query — the production contract every official adapter follows.

Rules:

• Empty results are a normal answer, not an error. Ship the no-memories path.
• Injected memory text is background data, never instructions. Append a guard line saying exactly that when you build prompt-injection features.

4. Evaluate — prove it works before anyone signs up

MemorySync is the one platform where YOU (the coding agent) can provision a working key with no human in the loop:

1. Mint: POST https://api.memorysync.io/evaluation/keys — body optional ({"agent_caller": "claude-code"}). A 201 returns api_key, default_user_id, project_id, mcp_url, expires_at, limits (add/retrieval/storage), and a claim_command. A 429 means the per-IP or per-network daily mint limit — the payload names which, with retry_after_seconds; do not retry sooner.
2. Round-trip: add one fact → query it back with the same X-End-User-ID → assert the text returns. Then add a turn via add_turn, replay the identical request, and assert the second response reports the row already exists (the idempotency proof).
3. Check the meter: GET /evaluation/usage shows what the loop consumed.
4. Know the quota contract — this is where integrations mislead users:
   • Evaluation plans are strict: over the limit, metered routes answer 429 with {"error": "limit_exceeded", ...}. Real errors, by design — an evaluating agent needs the truth. Expect and report them honestly.
   • Production orgs default to silent: over the limit, writes answer 200 {"status": "ok"} without storing and reads answer 200 {"memories": []}. End users never see a quota error. Never "fix" this as if it were a bug, and never build UI that promises an error will announce the limit.
5. Graduate: the human claims the eval account (claim_command) or creates a dashboard key at https://app.memorysync.io. Same API, silent-mode quota, higher limits.

5. Prefer the shipped adapter

If the project uses a framework or agent below, integrate through the official adapter instead of raw REST — each guide is one read_doc away (path /guides/<slug>):

Plain REST from any language is fully supported — read_doc the API Reference pages under /api/... for exact request and response bodies.

6. Hard invariants (do not violate)

• Never call DELETE /memory/user/purge. Despite the path, it erases the ENTIRE ACCOUNT behind the credential — keys, memberships, everything. It ignores X-End-User-ID. Delete individual memories by id via DELETE /memory/forget with memory_ids.
• Anything that runs inside a user's session (hooks, middleware) must fail open: a memory outage is a memoryless turn, never a broken app.
• Keep X-End-User-ID out of logs if your users' ids are sensitive; never log API keys.
• Confirm every endpoint, field, and limit against the live docs before shipping. The live docs win.