---

6.3 The memories table ¶

The single durable table. Every column and what it’s for:

id BIGSERIAL PRIMARY KEY

Surrogate key. Never reused.

user_id TEXT NOT NULL DEFAULT 'default'

Multi-user scaffolding. Always 'default' in single-user mode.

text TEXT NOT NULL

The user-facing fact, exactly as remembered.

normalized_text TEXT

Whitespace-collapsed, lowercased version of text. Drives the exact-duplicate detection via the unique partial index.

embedding vector(1536) NOT NULL

The pgvector vector that drives recall. Dimension must match Config.EMBEDDING_DIMENSIONS.

tags TEXT[] NOT NULL DEFAULT '{}'

Canonicalized lowercase tags. Indexed via GIN.

importance DOUBLE PRECISION NOT NULL DEFAULT 0.5

Reserved for future ranking work.

source_provider, source_client, source_conversation_id TEXT

Provenance fields recorded when the remembering client provides them.

embedding_provider TEXT NOT NULL DEFAULT 'openai'

embedding_model TEXT NOT NULL DEFAULT 'text-embedding-3-small'

Recorded per row so a re-embed walker can tell which rows have moved into the active model’s space. See Embedding Migration.

created_at, updated_at TIMESTAMPTZ NOT NULL DEFAULT now()

deleted_at TIMESTAMPTZ

updated_at is maintained by a trigger. deleted_at is NULL for active rows, populated on soft-delete.

metadata JSONB NOT NULL DEFAULT '{}'

Catch-all for non-indexed structured data. Currently holds capture_mode and session_id when supplied.

record_version INT NOT NULL DEFAULT 1

Per-record schema version. Drives the per-record upgrader framework (see The per-record upgrader framework).

expires_at TIMESTAMPTZ

last_confirmed_at TIMESTAMPTZ

Freshness fields. Recall excludes rows past expires_at.

forget_reason TEXT

replaced_by_id BIGINT REFERENCES memories(id)

Tombstone metadata — only set on rows that have been soft-deleted with a reason/replaced_by_id via the forget tool.

Indexes:

• memories_user_id_idx — B-tree on user_id.
• memories_created_at_idx — B-tree on created_at DESC.
• memories_deleted_at_idx — B-tree on deleted_at.
• memories_tags_idx — GIN on tags.
• memories_text_trgm_idx — GIN on text gin_trgm_ops, backs text_search.
• memories_embedding_idx — HNSW with vector_cosine_ops. Picked over IVFFLAT because IVFFLAT’s k-means seeding requires a populated table.
• memories_unique_normalized_active — partial unique on (user_id, normalized_text) WHERE deleted_at IS NULL AND normalized_text IS NOT NULL. Defense in depth against duplicate inserts; the service-layer dedup check fires first.