Migration & Upgrade

SmartMemory is pre-1.0 — minor releases can ship breaking changes. Here are the renames and removals you'll encounter when upgrading from earlier versions, with the one-liner fix for each.

Always re-read smart-memory-core/CHANGELOG.md and smart-memory-service/CHANGELOG.md before bumping.

CORE-MEMORY-DYNAMICS-1 M1b — `working` → `pending` (0.7.x)

The vestigial memory_type="working" bucket was renamed across the codebase. Most callers don't notice — the ConsolidationRouter now handles routing at ingest time — but a few public surfaces moved.

What changed

Before	After
`MemoryType.WORKING`	`MemoryType.PENDING`
`memory_type="working"`	`memory_type="pending"`
`WorkingMemory` class	`PendingMemory` class
`MemoryFactory.create_working_memory(...)`	`MemoryFactory.create_pending_memory(...)`
`get_working_memory()`	`get_pending_memory()`
`SmartMemory.commit_working_to_episodic()`	removed (router handles it)
`SmartMemory.commit_working_to_procedural()`	removed (router handles it)
`WorkingToEpisodicEvolver`, `WorkingToProceduralEvolver`	deleted
Config section `pipeline.working`	`pipeline.pending` (legacy key still read for one release)

How to migrate

# Find references
grep -rn 'memory_type="working"\|MemoryType\.WORKING\|create_working_memory' .

# Rename
sed -i '' 's/MemoryType\.WORKING/MemoryType.PENDING/g' your_code/*.py
sed -i '' 's/memory_type="working"/memory_type="pending"/g' your_code/*.py

If you were calling commit_working_to_*(), drop those calls — the ConsolidationRouter (added in M1a) now performs at-ingest routing. Inspect PipelineState.router_decision if you need the routing reason.

Data migration: none. The audit at rename time showed zero stored memory_type="working" rows in production. Hardcoded "working" queries return empty results until you rename them to "pending".

Package rename — `smartmemory` → `smartmemory-core` (0.5.0)

The PyPI distribution name changed. The Python import name is unchanged.

- pip install smartmemory
+ pip install smartmemory-core

  # imports stay the same
  from smartmemory import SmartMemory

The console script also renamed:

- smartmemory add "..."
+ smartmemory-core add "..."

Optional extras renamed in lockstep: pip install 'smartmemory-core[server]', pip install 'smartmemory-core[watch]'.

`add()` / `ingest()` swap (0.4.x)

Earlier versions overloaded add(). Method names now align with intent:

Method	Behaviour
`SmartMemory.ingest(content)`	Full pipeline (extract → store → link → enrich → evolve)
`SmartMemory.add(memory_item)`	Simple storage (normalize → store → embed)

If you were calling add() for full ingestion, switch to ingest(). If you were calling _add_basic() (private) for plain writes, use the public add(). The legacy ingest_old() and async-queueing path was removed — asynchronous ingestion now goes through ingest(sync=False) / ingest_batch().

`SmartMemory.init` — `scope_provider` parameter (0.3.x)

SmartMemory() no longer takes hardcoded scoping kwargs. Pass a ScopeProvider instance (or rely on the default for OSS usage):

- memory = SmartMemory(user_id="u", workspace_id="w")
+ memory = SmartMemory()                               # OSS / single-tenant
+ memory = SmartMemory(scope_provider=my_scope)        # multi-tenant service

The service layer's SecureSmartMemory already does this for you — no change needed in route handlers.

`PipelineState.simplified_sentences` (Pipeline v2)

simplified_text: Optional[str] was replaced with simplified_sentences: List[str] to support multi-sentence simplification.

- text = state.simplified_text or item.content
+ text = " ".join(state.simplified_sentences) if state.simplified_sentences else item.content

Ontology label unification (ONTO-RECONCILE-1, ongoing)

Legacy graph labels :EntityType, :Concept, :RelationType are being unified onto :OntologyType and :OntologyRelation. The migration is idempotent and runs in passes — it auto-pauses ingest while it's mid-flight. End user impact:

During the maintenance window, ingest() raises IngestPaused. Catch and retry with backoff.
After Task 11 ships, raw Cypher queries that match :EntityType / :RelationType will return zero rows; switch to :OntologyType / :OntologyRelation.

If you have custom Cypher in production, audit it before pulling the next core release. Run scripts/migrate_ontology_unify.py --status on the SmartMemory host to see the current pass and any HITL items.

`EventStream.read_all(limit)` removed (0.9.x)

read_all() was deprecated in 0.9.x and has since been removed — the method no longer exists on EventStream. Use read_recent(count), which pushes the bound to Redis instead of slicing in Python and prevents worker starvation on large streams.

- events = stream.read_all(limit=100)
+ events = stream.read_recent(count=100)

Upgrade procedure

Read both CHANGELOGs from your current version forward.
Bump smartmemory-core and smartmemory-service together — they ship in lockstep.
Run your test suite with the new dependency before deploying.
For service deploys, run a canary on one replica first; database migrations are idempotent but plugin discovery can fail loudly if a third-party plugin pinned an incompatible version range.
After deploy, watch docker logs svc-api for Failed to load entry-point plugin messages.