> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MemoryEngine

> How MemoryOS extracts, ranks, formats, and protects AI memory.

MemoryEngine is the runtime behind MemoryOS. It turns conversations into durable memories, retrieves the right ones at the right time, and returns prompt-ready context for your LLM.

It is not a vector search layer. It combines extraction, quality gates, conflict resolution, importance scoring, lifecycle management, version history, and graceful degradation.

## Write path

`POST /v1/memories/add` triggers this sequence:

1. Authenticate tenant and resolve `external_user_id`
2. Run quality gate (L1 rate → L2 quality → L3 dedup → L4 budget)
3. Create extraction job
4. Extract durable memories via LLM
5. Resolve conflicts against existing memories
6. Store in PostgreSQL
7. Write embeddings to Qdrant
8. Record version history
9. Run domain overlay if `domain_schema` is enabled

The API returns a `job_id` immediately. Extraction is async.

With the EdTech schema enabled, the domain overlay also updates `edtech_memories` with grade level, weak topics, learning style, and exam context alongside the normal memory path.

## Read path

`POST /v1/memories/retrieve` triggers this sequence:

1. Resolve tenant and user
2. Check quota and dependency mode
3. Load hot-tier memories from Redis
4. Search Qdrant for remaining slots
5. Rank by semantic relevance, importance, and recency
6. Filter archived and out-of-scope memories
7. Build `system_prompt_addition`
8. Prepend domain-aware context if a domain schema is active

## Context formats

`system_prompt_addition` comes in three formats:

| Format    | Use when                                        |
| --------- | ----------------------------------------------- |
| `bullets` | Prompt-ready natural language — the default     |
| `json`    | Your app parses memory context programmatically |
| `xml`     | Models that parse XML tags precisely            |

Example `bullets` output:

```text theme={null}
What you know about this user:
Skills & expertise:
- Comfortable with FastAPI and PostgreSQL.
Preferences:
- Prefers concise technical explanations.
- Likes Python-first examples.
```

## Conflict resolution

When a new memory contradicts an existing one, MemoryEngine resolves the conflict rather than storing both blindly.

| Old memory                        | New memory                           | Resolution                |
| --------------------------------- | ------------------------------------ | ------------------------- |
| User prefers JavaScript examples. | User now prefers Python examples.    | Old archived, new stored  |
| User works at Acme.               | User left Acme and joined Northstar. | Newer factual memory wins |

All conflict changes appear in version history. Routing is domain-aware — personal student facts go to user-session clarification, workspace-level facts go to tenant review.

Resolution paths in full:

| Path                  | Trigger                                    | Outcome                                                        |
| --------------------- | ------------------------------------------ | -------------------------------------------------------------- |
| Automatic update      | New memory supersedes older one            | Old archived, new stored with `previous_version_id`            |
| Merge                 | Two memories are compatible but incomplete | Merged memory stored, old archived                             |
| Reject                | Duplicate or lower quality                 | Incoming not stored                                            |
| Keep both             | Both still valid                           | Both kept with version history                                 |
| Cross-user recency    | One claim is much newer                    | Older claim weighted down                                      |
| Cross-user confidence | One claim has much higher confidence       | Lower-confidence claim weighted down                           |
| User clarification    | Personal conflict, only user can confirm   | Question surfaced on next `get()` via `clarification_question` |
| Tenant review         | Workspace or institution truth             | Tenant resolves in dashboard Conflicts page                    |

## Importance scoring

Each memory tracks:

* `original_importance_score` — set at extraction time
* `importance_score` — live score, changes with usage and decay
* `access_count` — how many times this memory has been retrieved
* `last_accessed_at` — last retrieval timestamp

Higher-importance memories rank higher. Stale low-value memories decay over time.

## Multi-provider extraction

Provider order is configurable:

```text theme={null}
LLM_PROVIDER_ORDER=gemini,openai,anthropic
```

If a provider fails with a timeout, 5xx, rate limit, or auth error, MemoryEngine falls through to the next one automatically.

## Related pages

* [Memory lifecycle and versioning](/concepts/memory-lifecycle)
* [Domain schemas](/concepts/domain-schemas)
* [Degradation Modes](/concepts/degradation)
* [Quality Gate](/concepts/quality-gate)