Migration & Upgrade

Some SmartMemory releases rename or remove public APIs. Here are the renames and removals you'll encounter when upgrading from earlier versions, with the fix for each.

Check the release history for smartmemory and smartmemory-core on PyPI before upgrading.

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 names: `smartmemory` and `smartmemory-core` (0.5.0)

In 0.5.0 the library's PyPI distribution was renamed from smartmemory to smartmemory-core. The Python import name is unchanged:

from smartmemory import SmartMemory

Today the package you install is smartmemory. It provides the smartmemory and sm commands and Lite mode, and it pins the exact matching smartmemory-core version, so installing or upgrading smartmemory brings the right library with it:

pip install -U smartmemory

`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 single-tenant use):

- memory = SmartMemory(user_id="u", workspace_id="w")
+ memory = SmartMemory()                               # 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 queries, audit them before pulling the next core release.

`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

Check the release history from your current version forward.
Upgrade the package. sm update checks PyPI, installs the latest smartmemory, and restarts the running daemon. pip install -U smartmemory also works. Either way the matching smartmemory-core comes with it.
Run your own test suite against the new version before rolling it out.
In Service mode, SmartMemory upgrades the managed API. You only upgrade the client packages you use, such as smartmemory or @smartmemory/sdk-js.