Skip to main content
MemoryEngine is the runtime engine behind MemoryOS. It turns conversations into durable memories, retrieves the right memories at the right time, and produces prompt-ready context for your AI application. It is not just a vector search layer. MemoryEngine combines extraction, quality gates, conflict resolution, importance scoring, lifecycle cleanup, version history, and graceful degradation. If a tenant has a domain schema enabled, MemoryEngine also runs a domain overlay after generic extraction and adds domain-aware context during retrieval. The SDK call stays the same.

​
Write path

When your app calls POST /v1/memories/add, MemoryEngine does not immediately write raw chat text into memory. The write path is:
  1. Validate tenant auth and external_user_id
  2. Run the quality gate
  3. Create an extraction job
  4. Extract durable memories from the conversation
  5. Resolve conflicts against existing memories
  6. Store canonical memories in PostgreSQL
  7. Write embeddings to Qdrant for retrieval
  8. Record memory versions for audit and debugging
  9. Run the tenant’s domain overlay if domain_schema is enabled
The request returns quickly with a job_id. Extraction runs in the background. For example, an EdTech tenant still stores normal generic memories, but the domain overlay also updates edtech_memories with grade level, weak topics, learning style, exam context, and forgetting stages.

​
Read path

When your app calls POST /v1/memories/retrieve, MemoryEngine retrieves memories and builds context that can be prepended to your model prompt. The read path is:
  1. Resolve the tenant and user
  2. Check quota and dependency mode
  3. Load hot-tier memories from Redis when available
  4. Search vector memory for remaining slots
  5. Rank with semantic relevance, importance, and recency
  6. Filter archived and out-of-scope memories
  7. Build system_prompt_addition
  8. Prepend domain-aware context if the tenant has an active domain schema
The returned system_prompt_addition is the safest field to pass into your LLM call.

​
ContextBuilder

ContextBuilder turns retrieved memories into high-quality model context. Supported formats:
FormatUse when
bulletsYou want prompt-ready natural-language context
jsonYour app parses memory context programmatically
xmlYou want strongly tagged context for models that follow XML well
Example bullets output: 
What you know about this user:
Skills & expertise:
- Comfortable with FastAPI and PostgreSQL.
- Has experience with retrieval systems.
Preferences:
- Prefers concise technical explanations.
- Likes Python-first examples.
ContextBuilder intentionally avoids exposing internal ranking details such as raw confidence or importance values inside the prompt text.

​
Conflict resolution

When a new extracted memory contradicts an existing one, MemoryOS resolves the conflict instead of blindly storing both. Examples:
Old memoryNew memoryResult
User prefers JavaScript examples.User now prefers Python examples.Old memory can be archived or superseded
User works at Acme.User left Acme and joined Northstar.Newer factual memory wins
Conflict changes are recorded in memory version history. Conflict routing is domain-aware. For an EdTech tenant, personal student facts such as exam_date, grade_level, and weak_topic route to user-session clarification. Shared institutional facts such as curriculum_standard or institution_policy route to tenant review. Unknown entities fall back to the generic router.

​
Resolution paths

MemoryOS uses several conflict resolution paths:
PathWhen it happensOutcome
Same-user automatic updateA new memory supersedes an older memory for the same userOld memory is archived and the new memory points to the previous version
Same-user mergeTwo memories are compatible but incomplete separatelyMemoryOS stores a merged memory and archives the old version
Same-user rejectThe new extracted memory is duplicate or lower qualityIncoming memory is rejected and not stored
Keep bothThe memories differ by time or both are still validBoth memories remain available with version history
Cross-user per-user scopedA conflict is actually personal to each userConflict is ignored as not a shared-context conflict
Cross-user recency weightedOne shared claim is much newer than the otherOlder claim is weighted down automatically
Cross-user confidence weightedOne shared claim has much higher confidenceLower-confidence claim is weighted down automatically
User-session clarificationThe conflict is personal and only the user can confirm itA question appears in the consent app’s Pending Questions tab
Tenant reviewThe conflict is about team, organization, institution, or workspace truthTenant admins resolve it in the dashboard Conflicts page
The consent app only shows conflicts from the user-session clarification path. Automatic resolutions and tenant-review conflicts do not appear in the user’s Pending Questions tab.

​
Domain overlays

Domain overlays add structured product-specific memory without changing the SDK. 
General engine:
  memories
  retrieval
  system_prompt_addition

Domain overlay:
  edtech_memories or another domain table
  domain retrieval context
  domain conflict routing
  optional domain profile endpoint
Use normal add() and get() for AI responses. Use optional domain helpers, such as get_edtech_profile(), only when building dashboards or analytics.

​
Importance scoring

Each memory has:
  • original_importance_score: extraction-time score
  • importance_score: live score that can change with usage and decay
  • access_count: retrieval count
  • last_accessed_at: last retrieval timestamp
Important memories are ranked higher. Stale low-value memories can decay over time.

​
Multi-provider extraction

MemoryEngine can use multiple LLM providers for extraction and conflict classification. Provider order is configured with: 
LLM_PROVIDER_ORDER=gemini,openai,anthropic
If one provider fails with a timeout, 5xx, rate limit, or auth error, MemoryOS falls through to the next configured provider. Operator health shows each provider as CLOSED, OPEN, HALF_OPEN, or NOT CONFIGURED.

​
Related pages