Core Concepts

Metadata, Tags & Sources

Add lightweight context that helps your application understand, filter, and trace a memory without putting private implementation details into the record.

Choose the right field

Field	Best for	Example
`source`	Where the memory originated.	`profile`, `chat`, `support`
`event_type`	What action produced it.	`preference_confirmed`
`tags`	Stable labels used in retrieval filters.	`preference`, `billing`
`metadata`	Small application-owned context.	`conversation_id`, `ticket_id`

Add useful context

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="user-123",
)

memory = client.add(
    "The user prefers weekly billing summaries.",
    source="settings",
    tags=["preference", "billing"],
    metadata={"setting_id": "billing-summary"},
)

Use stable names

Prefer short, lowercase source and tag values.
Define names in your application rather than generating a new label for each write.
Use metadata for traceability, not access control.
Store authoritative business data in its source system and reference it by an opaque ID when needed.

Keep sensitive data out

Do not store passwords, API keys, access tokens, hidden prompts, or encryption material.
Avoid direct personal identifiers when an opaque application ID is enough.
Keep metadata small and JSON-serializable.
Do not write reserved or undocumented system fields.

Filter with supported fields

Retrieval supports source and tag filters. Arbitrary metadata filtering is not part of the current public query contract.

Retrieval & Filters

See the exact nested filter shape.

Source Provenance

Use source and metadata to support your own traceability workflow.

Was this page helpful?

← Previous

Retrieval & Filters

Scopes & End Users