fix: use single connection for upsert_by_logical_key

[cmeans-claude-dev]

Summary

• Refactored upsert_by_logical_key in postgres_store.py to perform the INSERT attempt, existing-row fetch, and conditional UPDATE within a single pooled connection and transaction
• Previously acquired up to 3 separate connections (_query_entries and update_entry each took their own), causing unnecessary pool contention under concurrency
• Addresses MEDIUM Non-blocking cleanup, tools reference, screenshot resize #2 from the code audit

QA

Prerequisites

• pip install -e ".[dev]"
• Deploy to test instance on alternate port (AWARENESS_PORT=8421)

Manual tests (via MCP tools)

1. • Create entry via upsert

   remember(source="qa-upsert-test", description="original description", tags=["qa-upsert"], logical_key="upsert-qa-key")
   

   Expected: entry created successfully, returns the new entry

2. • Update entry via upsert (same logical_key)

   remember(source="qa-upsert-test", description="updated description", tags=["qa-upsert", "v2"], logical_key="upsert-qa-key")
   

   Expected: existing entry updated (not duplicated), description and tags reflect new values, changelog records the change

3. • Verify single entry exists

   get_knowledge(source="qa-upsert-test", tags=["qa-upsert"])
   

   Expected: exactly one entry with logical_key="upsert-qa-key", showing updated description and tags

4. • Cleanup

   delete_entry(id="<entry-id-from-step-1>")
   

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Review — PR #135: Single-connection upsert_by_logical_key (MEDIUM #2)

Reviewer: QA Agent | Date: 2026-03-31

Code Review: PASS

The entire upsert flow (INSERT attempt, existing-row fetch, diff computation, conditional UPDATE) now runs within one with self._pool.connection() as conn, conn.transaction(), conn.cursor() as cur: block. Previously acquired up to 3 connections via _query_entries and update_entry.

Key implementation details:

• Uses _load_sql("query_entries").format(...) directly instead of calling _query_entries — avoids the separate connection that method acquires.
• Update logic inlined (changelog computation, update_entry SQL) — mirrors update_entry behavior but within the existing cursor.
• Early return for no-diff case (if not updates: return (old, False)) — skips unnecessary UPDATE.
• _cleanup_expired() only called on insert path (correct — updates don't create new entries).

Tests: 554/554 PASS

New test_upsert_by_logical_key_creates_then_updates covers create→update→changelog→single-entry verification. Existing concurrent upsert test still passes.

CI: All green

Findings: Zero

[cmeans]

QA Audit — PR #135

CI: All green | Tests: 554/554 pass

#	Severity	Finding
—	—	No findings
Adding Ready for QA Signoff.

[cmeans]

LGTM