Troubleshooting

The failures integrators run into most, each with the cause and the fix. Where Pitfalls is prevention, this is diagnosis — start here when something's already wrong.

Construction & connection

PgMem.create fails on embedding dimension. The schema is fixed at vector(1536) and your embedder reports a different dimension. Use a 1536-dim model (e.g. OpenAI text-embedding-3-small) or set the matching expected_embed_dim. See Connect a model provider.

Connection or relation "pgmem.…" does not exist errors. The schema isn't applied to this database. Run the installer against your $DATABASE_URL and confirm — see Installation:

psql "$DATABASE_URL" -c "SELECT version FROM pgmem.schema_migrations ORDER BY version;"

Nothing seems to be stored

An active claim is missing from context. Confirm its scope and subject match the session, its lifecycle status is active, and the claim policy did not hold or reject the observation. Query the claim ledger directly when investigating; it is the authoritative record.

A projection is missing or stale. Claim projections are asynchronous. End the session and let the projection worker refresh vector, graph, and narrative projections. Check the worker's result and retry state; do not use a projection as proof that the underlying claim was lost.

add_episode created nothing / raised. It needs both an embedder and an llm. Without them the graph is skipped silently on reads and errors on writes. See Connect a model provider.

Search returns nothing

Empty claim recall results. Claim recall is full-text — the query must share terms with the stored claim. "July rollout" matches "targeting a July rollout"; a semantically similar but lexically different query will not.

Empty mem.search (graph) results. The graph needs an embedder wired, and its knowledge must have been explicitly ingested with add_episode. Confirm both, then check you're passing the right group_ids. Session claims do not implicitly create graph entities and edges.

Latency & concurrency

Turns are slow / stalling. Something heavy is on the response path. Only compile_context belongs on a turn; add_episode, compact, projection refresh, and a construction-time injected_context_provider must run off it. See Latency & voice safety.

compact_async or the worker hangs / contends. They hold one connection while working on another. Set pool.max_size >= 2 (higher for concurrent groups).

compile_context reports compaction_triggered but nothing compacted. That's the budget fitter trimming recent turns for one prompt — not durable compaction. Call compact_async() off-turn to actually compact.

Multi-tenancy

Memory leaking across tenants, or a session not found. Every top-level call is scoped by group_id, and resume/summarize_saga require it. A missing or wrong group_id either leaks data or fails the lookup. See Multi-tenancy & isolation.

Still stuck?

Inspect what pgmem actually stored — compactions, claim evidence, projection status — with the read surfaces in Inspecting memory.

Related

• Pitfalls & footguns — avoid these up front
• Inspecting memory — audit what's stored
• Latency & voice safety — the response-path rule