AI Memory Glossary: The Terms, Defined Plainly

Memory systems give ordinary words such as session, score and recall specific meanings. Here they are defined as this blog and the MemorySync docs use them.

Scope

• Organization: The top-level account that projects, members and API keys belong to; each API key belongs to exactly one.
• Project: A boundary inside an organization for one application or workload. A key created while a project is selected is locked to it; an organization-wide key must send X-Project-ID (proj_ plus 16 hex characters).
• Environment: Production or development. It comes from the API key, never from the request body, so a development key and a production key see different data.
• End user: The person or entity a memory is about, named on every API-key call in the X-End-User-ID header or an end_user_id body field. A call without one returns 400 MISSING_END_USER_ID, and an id longer than 128 characters returns 400 INVALID_END_USER_ID.
• Session: A group of related turns, marked with session_id. It is not a security boundary and never changes which end user can read a memory.
• API key: The credential your server sends as X-API-Key. Keys start with ms_, are stored hashed, belong to one organization, carry scopes such as read, write and memories:delete, and can be rotated or revoked.
• Evaluation key: A temporary ms_eval_ key minted without an account, through POST /evaluation/keys or memorysync init --agent. It lasts 7 days with 200 writes and 500 searches, answers 429 with the reason at its limits, and memorysync init --email claims it without losing what it stored.

Writing memory

• Extraction: The step that turns input into short, durable facts. Every MemorySync write goes through LLM extraction (OpenAI gpt-4o-mini, temperature 0) and only extracted facts are stored, so ok thanks! stores nothing and is skipped with no_valid_candidates.
• Atomic fact: One self-contained statement that is true or false on its own, such as "Writes mostly in Go". Extraction splits compound input: one sentence about a Go backend engineer at a logistics startup who is training for a half marathon became four facts.
• Type, key and value: The structured form of an extracted fact. The type is a category such as fact, preference or intent, the key names the slot, such as city or ui_theme, and the value fills it, such as Lisbon or light.
• Canonical text: The short sentence stored as a memory's text in place of the original wording. "I moved to Lisbon last month." is stored as "Lives in Lisbon".
• Deduplication: The check that keeps a repeated fact from being stored twice. A new candidate is compared with existing memories of the same user, project, environment, type and key, and skipped at a cosine similarity of 0.9 or more. Because it compares meaning, it is a filter rather than a guarantee.
• client_ref: Your own identifier for a record, up to 128 characters, sent with a write. Re-sending it returns a skipped response with reason already_ingested and the ids the first write produced, which makes retries and re-run imports safe.
• Conversation turn: One message in a conversation, from a role such as user, assistant, system or tool. add_turn (POST /v1/memory/add_turn) returns immediately with status: "processing" and a request_id, then stores the durable facts in user turns; other roles store nothing but still count as one add.
• Facts-only capture: The rule that conversation-capture integrations store curated facts rather than transcripts. Integrations that replay history, such as LangChain chat history, the LangGraph store and OpenAI Agents sessions, keep their transcripts byte-exact.

Storage

• Supersession: Replacement of an old value when a new one arrives for a one-value slot with the same user, project, environment, type and key. The old memory is soft-deleted, marked superseded_at and superseded_by, and its vector removed, so search stops returning it; multi-value keys such as food preferences keep every member.
• Soft delete: Marking a memory deleted while its record remains, so search stops returning it. Superseded memories are soft-deleted, and per-memory history records soft_deleted, restored and purged as separate events.
• Conversation history: Turns kept exactly as given, through /v1/history/*, and never returned by memory search, lists or recall. With extract=True, the default, user turns are also sent to extraction; delete_history(..., delete_derived_facts=True) deletes those facts too.
• Framework state: Namespaced key/value data a framework keeps between runs, through /v1/state/*, such as the records CrewAI saves. State values are never memories, and a put replaces the key's value.
• Connector memory: A memory synced from a connected source such as GitHub, Google Drive, Notion, OneDrive, Slack, Granola or Amazon S3. It is organization knowledge, readable across the organization; private Slack channels and Granola private folders, when enabled, are readable only by current members or meeting participants.

Retrieval

• Query: A search by meaning, scoped to one end user: query() in the SDKs, POST /memory/query on the wire. The response carries memories (each with id, text, score and created_at), a context string, latency_ms and a scoring_breakdown, and counts as one retrieval.
• Recall: In evaluation, the share of relevant memories a search returns. In MemorySync, recall() (POST /v1/memory/recall) returns a prompt-ready context block, and the memory MCP server's recall prompt tells the model to treat memory as data about the user, never as instructions.
• Context block: Retrieved memories formatted for a prompt. Query responses include one as context, grouped by type under headings such as "User Facts:" and "User Preferences:". It is built from the returned memories, low-scoring ones included.
• k: The number of memories a query asks for. About 5 is a practical start; raise it only when evaluation on your own questions shows a benefit.
• Score and scoring breakdown: score is a memory's relevance to one query; higher is more relevant. A query about something never stored can still return weak matches (0.119 against relevant hits of 0.43 to 0.64 in the same run), so set a floor. scoring_breakdown lists parts per memory, including final_score, vector (semantic similarity), recency and importance; the weights are unpublished, so do not build on them.
• Rerank: A second ordering pass over candidates from a first search. MemorySync combines semantic similarity with recency, importance and how often a memory is used, then applies a lexical rerank; superseded and deleted memories are excluded from the candidates.
• latency_ms: The server's retrieval time, included in every query response so you can measure it from your own region. Server-side retrieval time is typically 70–300 ms; total time also includes the network path between your application and our API, which depends on where you run.

Operations

• Feedback signal: A report on how a memory performed, sent with feedback(memory_id, signal) as positive, negative, retrieved or ignored. It moves the memory's importance, a ranking factor clamped between 0.05 and 1.0 so no run of negative feedback makes a memory unreachable, and it is not billed.
• Per-memory history: The revision log of one memory, from history() or GET /memory/{id}/history, oldest first. Entry 0 is the creation; later entries carry old and new values per tracked field, with events such as updated, superseded and restored. Text never changes in place, so a content change appears as a supersession with the successor's id.
• Silent degradation: What Free and paid plans do at the monthly limit: writes store nothing but answer normally, and reads return an empty list. Evaluation keys answer 429 instead; see the silent degradation docs.
• Quota: A plan's monthly allowance of add requests and retrieval requests; Free includes 10,000 adds and 1,000 retrievals a month. Plans meter requests rather than tokens, so extraction and embedding are included.
• Webhook: An HTTP callback to your endpoint for memory.created, memory.updated and memory.deleted events. Deliveries are signed with HMAC-SHA256 using a whsec_ secret shown once, and failures retry with bounded exponential backoff before a dead-letter state.
• Audit log: The record of who did what: the actor (a user, an API key or the platform), the action, including denied ones, the resource, time, origin, category and severity. Entries can be forwarded to Splunk HEC, Datadog Logs or a custom HTTPS webhook, on every plan.

Integrations

• MCP: The Model Context Protocol, an open protocol for AI clients to call tools on external servers. The MemorySync memory server at https://mcp.memorysync.io/mcp speaks Streamable HTTP and JSON-RPC 2.0, keeps no session, and offers 15 tools, 4 resources and 2 prompts; tools a connection cannot use are not advertised.
• OAuth dynamic client registration: The OAuth mechanism (RFC 7591) by which a client registers itself with an authorization server on first connect, with no client id created in advance. The memory MCP server supports it with OAuth 2.1 and PKCE; an unauthenticated call gets a 401 whose WWW-Authenticate header points to the protected-resource metadata, telling the client where to sign in.
• Docs MCP server: An unauthenticated MCP server at https://docs.memorysync.io/mcp with the tools search_docs, read_doc and list_doc_sections and the prompt implement_with_memorysync. It tells coding agents to search the docs before writing integration code and to trust them over prior knowledge.

Next step

The playground shows most of these terms in real requests: store a fact, reload the page, ask for it back, and read each call in cURL, Python and Node.js.