Memory OS runtime harness

Persistent agent memory through MCP and SDK.

Memory OS turns natural-language user work into typed, scoped, governable memory. Cursor connects through MCP, observes normal turns, classifies durable signals, stores them with salience and utility, links related memories, recalls only what matters, and checks risky actions before the agent moves.

What happens when the user talks

The user speaks naturally. The agent does not ask them to manage a memory database. MCP gives the agent tools; the agent initializes memory, observes the user turn, and only stores the message if classification says it contains durable operational signal.

memory_initLoads the stable agent identity and the most salient standing context for the conversation.

memory_observeClassifies the literal user turn and stores durable memory without adding recalled memories to context.

memory_recallRetrieves typed memories when they can improve planning, coding, debugging, or product decisions.

memory_check_actionRuns a safety check before risky or irreversible actions.

Why this is not vanilla RAG

RAG asks “which chunks are close to this query?” Memory OS asks “which previous experience should govern this agent’s next action?” That requires type, scope, confidence, salience, utility, recency, relations, lifecycle, and action gates.

Vanilla RAG Retrieves text. Usually lacks durable typed decisions, project boundaries, utility feedback, decay, and action blocking.

Mem0-style memory Captures useful user memories, but does not fully model governed agent operations, lifecycle, eval feedback, and procedural gates.

Memory OS Stores operational memory with typed classification, scoped entities, graph linkages, utility, lifecycle, recall profiles, and governance.

The actual Memory OS runtime flow

Each module maps to the real MCP/runtime path: user message, classification, storage, scoring, relation wiring, recall, governance, feedback, lifecycle, and audit.

Memory classification layer

Each memory type has a different job, different weight, and different decay behavior. This is why Memory OS does not store everything as one generic note.

instruction

Instruction

Example: never print API keys in deployment logs.

Highest priority. It barely decays because a standing rule should still protect the agent months later.

decision

Decision

Example: use Cloudflare for the MCP edge endpoint.

High priority. It decays slowly, but newer decisions can supersede older direction.

preference

Preference

Example: use careful language in team presentations.

Medium high priority. It shapes style and taste, but should not override hard instructions.

fact

Fact

Example: the app deploys to Cloud Run in europe west one.

Medium priority. Current state can become stale, so facts decay faster than decisions.

mistake

Mistake

Example: deploying to the wrong workspace created production risk.

High priority. Mistakes become lessons so the agent does not repeat known failures.

procedure

Procedure

Example: before production SQL, preview rows and ask for approval.

Medium high priority. Procedures become checklists and gates, not just context.

relationship

Relationship

Example: Cloudflare MCP route relates to Cursor installation.

Structural priority. Relationships connect memories so recall can use graph support.

context

Context

Example: this chat is about presenting the Memory OS runtime.

Lowest priority. Context is useful now, but intentionally fades fastest.

Memory border width

Globalstanding rules across work

Agentstable Cursor identity

Projectrepo and product boundary

Sessiontemporary local context

Ranking recipe

Weightpriority multiplier by memory type and task profile

Salienceinfluence score from type, explicitness, recency, confidence, access, and relevance

Utilitylearned boost or penalty from useful, ignored, wrong, or harmful feedback

Graphrelation support from co occurrence, supersession, and generalized memories

Decay and lifecycle

active

high value, current, or protected memory shapes responses

dormant

low salience memory stays available but stops dominating

suppressed

superseded or harmful memory loses influence quickly

archived

weak unprotected memory is removed from normal recall

Why normal systems fail

Generic memory stores text. Memory OS stores operational meaning. A rule, a decision, a mistake, and a temporary fact cannot share one ranking policy without causing stale context, weak governance, or repeated errors.

How storage works

Each memory keeps type, key, value, confidence, salience, tags, utility, state, validity, access counts, supersession, and optional embedding so later recall and lifecycle have real control signals.

How linkages form

Co recalled memories gain relation support. New truth can supersede old truth. Related low salience memories can synthesize into a generalized memory while preserving provenance.

Classification is the gateway.

The system decides whether the user is asking, instructing, deciding, correcting, or stating. It returns shouldStore, type, scope, confidence, reason, risk, tags, and a stable key.

Ranking is not just vectors.

Recall blends semantic similarity, lexical anchors, salience, type weights, utility, graph support, and expression state so the right operational memory beats a merely similar chunk.

Memory changes over time.

Feedback adjusts utility, access changes recent strength, supersession suppresses stale truth, and lifecycle decay moves low-value memories toward dormancy or archive.