Memory Provenance

Track where memories came from, which service wrote them, and how conflicts are resolved.

Provenance answers three questions about a memory:

• Who wrote it? Which service, API key, Passport agent, or organisation connection observed the claim.
• Where did it come from? Which source event, payload hash, and evidence references produced it.
• Why is this version active? Which authority, recency, confidence, or human decision selected it over another claim.

This is the governance layer behind MemoryOS. It matters most when multiple services or agents write memories about the same user.

Core objects

Service Writer

A Service Writer is a named identity for one backend service. Register one writer for each service that observes user facts.

Examples:

• support-service
• billing-service
• crm-sync
• learning-platform

Field	Meaning
service_key	Stable slug, for example billing-service
display_name	Human-readable label in dashboards
authority_rules	Priority scores per memory category
api_key_id	Optional bound API key for credential verification

Source event

A source event is created for an add() call that includes a source block. It records:

• your system event ID
• when your system observed the event
• which service wrote it
• SHA-256 payload hash
• optional evidence references
• optional scope metadata

Every memory created by that job points back to the source event.

Claim revision ledger

MemoryOS keeps claim revisions so conflict resolution does not erase history. When a newer or more trusted claim supersedes an older one, the older claim is archived instead of deleted.

The active memory is what retrieval sees. The ledger keeps the full lineage for audit, dashboard inspection, and future graph work.

Register a Service Writer

POST /v1/tenant/service-writers
Authorization: ApiKey mem_live_xxx
Content-Type: application/json

{
  "service_key": "billing-service",
  "display_name": "Billing Service",
  "authority_rules": {
    "default_priority": 50,
    "categories": {
      "fact": 80,
      "preference": 40,
      "goal": 50
    }
  }
}

Use separate API keys per service in production. Bind each writer to its key from the Tenant Dashboard when you are ready for production traffic.

Send source metadata on add()

POST /v1/memories/add
Authorization: ApiKey mem_live_xxx
Content-Type: application/json

{
  "external_user_id": "customer_123",
  "messages": [
    {
      "role": "user",
      "content": "What plan am I currently using?"
    },
    {
      "role": "assistant",
      "content": "Your current subscription plan is Growth."
    }
  ],
  "source": {
    "service": "billing-service",
    "event_id": "billing-plan-2026-06-30-001",
    "observed_at": "2026-06-30T10:00:00Z",
    "scope": {
      "workspace_id": "ws_123"
    },
    "evidence": [
      {
        "source_type": "subscription_record",
        "reference": "billing/subscriptions/ws_123"
      }
    ]
  }
}

Field	Required	Notes
service	Yes	Registered service_key
event_id	Yes	Stable event ID from your system
observed_at	No	Defaults to request time if omitted
scope	No	JSON metadata such as workspace, region, channel, or ticket
evidence	No	References to records in your system; do not include secrets

Idempotency and payload safety

Retrying the same source.event_id with the same payload returns the original job path and does not duplicate extraction.

Retrying the same source.event_id with different messages returns a provenance conflict error. This prevents accidental mutation of historical source events.

Raw extraction payloads can be redacted after the configured retention window. The payload hash stays so the source event remains verifiable.

Conflict resolution

When two writers produce conflicting memories for the same user, MemoryOS compares claims using this order:

1. Writer authority for the memory category
2. Source observed_at recency
3. Extraction confidence
4. Human review when equally trusted sources disagree

Example authority rules:

{
  "default_priority": 50,
  "categories": {
    "fact": 90,
    "preference": 40
  }
}

A billing service can be trusted more for subscription facts, while a chat service may be trusted more for user preferences.

Equal-authority conflicts

If equally trusted services disagree, MemoryOS does not silently choose one. It creates a review item.

Example:

• Support Service reports: User's current subscription plan is Starter.
• Billing Service reports: User's current subscription plan is Growth.

If both have equal authority, the tenant dashboard shows the conflict for review. If it is a personal Memory Passport conflict, it appears in the user’s Pending Questions tab.

The losing claim is not hard-deleted. It is kept in the revision ledger and marked inactive or archived.

Provenance in retrieve responses

retrieve and list include provenance when available:

{
  "content": "User's current subscription plan is Growth.",
  "category": "fact",
  "source_event_id": "3c3994d0-1c1d-4e1a-9fd1-0f87f82d13da",
  "provenance": {
    "service": "billing-service",
    "event_id": "billing-plan-2026-06-30-001",
    "observed_at": "2026-06-30T10:00:00Z",
    "received_at": "2026-06-30T10:00:02Z",
    "payload_hash": "7ba8601d36046350e1311f08b7a66646338ee75e3b443ebaba35de9607b6e169",
    "scope": {
      "workspace_id": "ws_123"
    }
  }
}

Legacy memories may have partial provenance. The Operator Console shows provenance coverage and unattributed lineage so the MemoryOS team can backfill safely.

Inspect source events

GET /v1/tenant/source-events?external_user_id=customer_123&source_service=billing-service&limit=50
Authorization: ApiKey mem_live_xxx

Use this endpoint to inspect source events, payload hashes, linked extraction jobs, evidence references, and scope metadata.

Error codes

Code	Meaning
PROV_403	API key does not match the writer’s bound key
PROV_404	Service writer not found
PROV_409	Source event exists with a different payload, or writer key already exists
PROV_422	Invalid service writer or source payload

Who needs provenance?

Scenario	Need provenance?
One simple app writing memories	Optional
Multiple services writing for the same user	Yes
Compliance audit trail	Yes
Exactly-once ingestion with retries	Yes
Conflict resolution between services	Yes
Memory Passport shared context	Yes

Related pages

• Extraction Quality Loop
• Memory Lifecycle and Versioning
• POST /v1/memories/add
• POST /v1/memories/retrieve