Operational memory API

The MemoryStore contract

lumis_sdk.ports.MemoryStore is the asynchronous contract for retained incident episodes, explicit confirmed resolutions, and transparent bounded retrieval. incident_id is an idempotency key: repeating identical content is safe, while different content for the same key raises MemoryConflictError. A resolution must target a saved episode, and model text never changes truth state.

from pathlib import Path

from lumis_sdk.adapters.sqlite import SQLiteMemoryStore
from lumis_sdk.testkit import assert_memory_store_contract

store = SQLiteMemoryStore(Path(".lumis/portable-memory.db"))
await assert_memory_store_contract(store)

assert_memory_store_contract runs the full behavioral contract against any implementation, so an independent adapter can prove it behaves exactly like the reference stores.

PostgreSQL plugin

For durable shared memory across a team, install the independently packaged plugin alongside a compatible core release:

pip install "lumis-sdk==0.0.8" "lumis-sdk-postgres-memory==0.1.1"

from lumis_postgres_memory import PostgresMemoryPlugin
from lumis_sdk.config import PostgresMemoryConfig

config = PostgresMemoryConfig(
    provider="postgres",
    connectionUrlEnv="LUMIS_MEMORY_DATABASE_URL",
    schema="lumis_memory",
)
store = PostgresMemoryPlugin().create(config)

The plugin declares network and secret authority in its manifest and reads only the named environment variable. Migrations are serialized, schema identifiers are validated, candidate reads are bounded, and search reasons use the same deterministic ranking contract as SQLite.

Queries and scoring

MemoryQuery combines text with optional classification and pipeline filters; reusable_only=True returns only human- or verification-confirmed records. Every MemoryMatch exposes a score, human-readable reasons, and score_components (lexical, filters, truth), keeping ranking fully explainable.