Terminology Glossary

Tenant

A single isolated namespace within MemoryWell. Every API key belongs to exactly one tenant. All data, operations, and logs are scoped by tenant_id — derived from the authenticated session, never from the request payload.

tenant_id = hash(user_email + app_id)

Bottle

The fundamental storage unit. A Bottle contains a conversation (or snippet) plus metadata. Every memory lives in a Bottle. Bottles are immutable once written — updates create new versions.

MemoryBottle { id, app_id (=tenant_id), bottle_name, full_conversation[], message_count, storage_tier }

Memory

A single piece of stored knowledge. In the API, 'storing a memory' = creating a Bottle with your content. Memories are searchable semantically (by meaning) and retrievable by ID or idempotency key.

POST /mwStoreMemory → creates MemoryBottle → queued → catalogued

Outbox

A durable fallback queue. When the primary Redis queue is unavailable, operations are written to the Outbox entity in the database. The repair sweep picks these up and re-queues them. No silent drops.

Outbox { op_type, payload, status, retry_count, tenant_id }

Invariant

A property the system guarantees will always be true, regardless of concurrent operations, retries, or failures. MemoryWell maintains 4 core invariants (S1–S4): exactly-once writes, tenant isolation, audit completeness, and recoverability.

S1: One canonical bottle per idempotency_key per tenant
S2: Zero cross-tenant reads or writes
S3: Every operation in AuditLog
S4: Any state recoverable from export snapshot

Entropy

The accumulation of inconsistency: orphaned records, duplicate bottles, unacknowledged jobs, or data that exists in one entity but not another. Target entropy = 0. Measured and tracked by the integrity sweep.

entropy = orphan_bottles + stuck_jobs + unreconciled_outbox_items

Queue Worker

The background process that pops jobs from Redis, executes them (store, recall, search), updates JobStatus, and handles retry with exponential backoff. Runs on a 5-minute scheduled automation. Not a daemon — invoked on schedule.

mwQueueWorkerV2 → LPOP mw:queue:work → process → update JobStatus → sleep

DR Drill

Disaster Recovery drill. A scripted procedure that exports all tenant data, verifies the SHA-256 hash, imports to a clean state, and confirms record count parity. Proven in Stage 12. Must be re-run quarterly.

mwExportSnapshot → verify hash → mwImportSnapshot → assert count match

Capability

An explicit grant that allows a specific operation beyond standard tenant access. Stored in CapabilityGrant entity. Admin-only endpoints require capability check before executing. Violations are logged.

CapabilityGrant { user_email, capability_type, granted_by, expires_at }

Idempotency Key

A client-supplied string that makes a store operation safe to retry. If you submit the same key twice, exactly one Bottle is created — the second call finds the existing record and returns it. Prevents duplicates under network retries or concurrent storms.

idempotency_key = 'user-pref-darkmode-v1'  # deterministic, client-chosen

TTFS / TTFV

Time To First Store / Time To First Value. The core beta success metrics. TTFS = how long from key issuance to first successful store. TTFV = how long until the developer retrieves something useful. Target: TTFS < 10 min, TTFV < 30 min.

beta_log { dev_email, key_issued_at, first_store_at, first_recall_at, friction_notes }