Refuse property values that some store refuses or alters where an episode enters - #1792

Purpose of the change

Summary

An episode's data fans out to the episode store, semantic memory, and episodic memory's segment store and vector store at once. Each value that becomes a property value (a metadata key or value, the producer, the recipient, the role, or the timestamp) was accepted as any string, number, or datetime, so a value that one store refuses was written by the others first, and the request answered 500 with the episode in some stores and not in others. A value that one store alters was kept as given in the others.

This change refuses those values where an episode enters, before any store is called:

• POST /api/v2/memories answers 422.
• MemMachine.add_episodes callers get a ValidationError when they build the EpisodeEntry.

The property value domain is defined once, in memmachine_common.api.spec:

• booleans;
• signed 64-bit integers;
• finite floats;
• strings free of U+0000 and surrogate code points;
• datetimes whose UTC offset is a whole number of minutes and whose UTC instant falls in years 1 through 9999.

validate_property_value checks any property value, PropertyStr types a string, and PropertyDatetime types a datetime. MemoryMessage types its metadata keys and values, producer, produced_for, and role as PropertyStr and its timestamp as PropertyDatetime. EpisodeEntry types producer_id, producer_role, produced_for_id, and its metadata keys as PropertyStr, and checks created_at and its metadata values that are property values. Metadata values that are lists, objects, or null are kept as they are.

What each store does with these values on main (measured; full matrix in the issues):

The domain is checked where an episode enters, not on the shared PropertyValue alias. The stores' own models (Record, Event, Segment, and Episode) carry that alias, so a check on it would:

• preempt each store's own checks on its input;
• run again for every record read back: Record validation with 12 properties went from 5.6 µs to 9.7 µs in a local measurement;
• fail semantic memory's vector records after their SQL rows are written.

The alias stays as it was.

Fixes #1793. Fixes #1794. Fixes #1795. Part of the fix for #1784, whose store-side refusal is in #1788.

Not covered here, each with its own issue:

• Event-backend sessions refuse metadata keys outside the vector stores' key set after the episode store and semantic memory have written the episode #1796: event-backend sessions refuse metadata keys outside the vector stores' key set, or starting with an underscore, after other stores have written the episode.
• PostgreSQL JSONB reads float property values of 1e16 or more back as integers, making their segments unreadable, and -0.0 as 0.0 #1797: PostgreSQL JSONB reads float property values of 1e16 or more back as integers, and -0.0 as 0.0.
• Long property strings are refused by Milvus and by PostgreSQL indexes after other stores have written them #1798: long property strings are refused by Milvus and by PostgreSQL indexes after other stores have written them.
• Message content with U+0000 or a lone surrogate is refused by the episode store after the other stores have written it #1799: message content with U+0000 or a lone surrogate is refused by the episode store after the other stores have written it.
• Add-memories timestamps that are naive ISO strings or out-of-range Unix times answer 500 #1800: a naive ISO timestamp string, or an out-of-range Unix time, answers 500.

Commits

1. Refuse property values outside the domain when an episode entry is built
2. Refuse add-memories property values outside the domain with 422

Stack

21 open PRs: three independent PRs, and the vector store tree of short parallel branches. Every PR in the tree has feat/horizontal-scaling as its GitHub base, and the independent PRs have main. The branches are in a fork, and a pull request can target only this repository's branches, so the on column gives the order the PRs build on each other. A stacked PR's diff on GitHub includes the PRs under it until they merge.

Independent of the vector store tree, directly on main:

The vector store tree. Each PR builds on the one in its on column; PRs on the same parent are parallel branches and do not depend on each other. #1631 is closed, superseded by #1733–#1736, which hold its changes split in four, with review changes since. #1702 and #1670 sit beneath #1627, whose code depends on them. Until the PRs under it merge, their changes show in a stacked PR's diff.

This PR is its 2 commits, ab419b16f, 95ded7618, directly on main, independent of the vector store tree: review and merge it in any order.

Verification

• Store-level measurement on main at ad8ff24, one value at a time through each store's own code, with a throwaway probe that is not committed:

  • episode store on SQLite and PostgreSQL;
  • semantic memory set registration through SemanticSessionManager.add_message on pgvector storage and vector-store storage, on SQLite and PostgreSQL;
  • LongTermMemory on the event backend into the SQLAlchemy segment store on SQLite and PostgreSQL;
  • LongTermMemory into SQLiteVectorStore, SQLiteVecVectorStore, Qdrant 1.17.0 over REST and gRPC and in local mode, and Milvus 2.6.24 and Milvus Lite, with and without a declared user property schema.

• POST /api/v2/memories end to end through MemMachine.add_episodes, with the real episode store, segment store, and semantic storage on SQLite and on PostgreSQL and SQLiteVectorStore, counting rows in each store after every request:

  request	before	after
  metadata value with U+0000	SQLite: 200, stored everywhere; PostgreSQL: 500, only semantic sets written	422, nothing written
  metadata value with a lone surrogate	SQLite: 200; PostgreSQL: 500, only semantic sets written	422, nothing written
  producer with U+0000	SQLite: 200; PostgreSQL: 500	422, nothing written
  timestamp 0001-01-01T00:00:00+05:00	500	422, nothing written
  timestamp 2026-01-01T12:00:00+05:30:45	200	422, nothing written
  metadata {"k": "v"}	200	200, stored everywhere

• uv run --frozen --all-extras ruff check and ruff format --check: clean.

• ty check: packages/server with Python 3.12 and 3.14, and packages/common and packages/client with Python 3.10 and 3.14: clean.

• uv lock --check: clean.

• Unit suite (pytest packages): 2405 passed, 3 skipped.

• Integration suite (-m "integration and not slow" over the four CI paths), with PostgreSQL, Neo4j, and Qdrant 1.17.0 containers: 1454 passed, 188 skipped (tests that need an OpenAI or AWS key).

• Each test fails under the mutations named in its commit message, which were each applied and run.

• git merge-tree --write-tree upstream/feat/horizontal-scaling HEAD: no conflicts.

🤖 Generated with Claude Code