Skip to content

pycontextdb 0.4.6: user facts stay put, and actions rely on the right memory

Choose a tag to compare

@atomsai atomsai released this 08 Oct 11:24
cea7c13

User facts stay put, and actions rely on the right memory

pycontextdb 0.4.6 makes three trust fixes to the open-source ContextDB SDK:

  • A stored email, ticket, document, or agent guess can no longer overwrite what the user said.
  • recall_for_action can be told which fact an action needs, so an unrelated trusted memory no longer counts as a reason to act.
  • A billing email, work phone, or work address no longer erases the personal one.

What was wrong in 0.4.5:

  • Every write under one user id counted as the same speaker. A third-party document or an agent inference stored for that user looked like the user correcting themselves, so it superseded their own fact in the same slot. The agent would then ask the user to confirm the document's value. This is advisory GHSA-vpf9-5xgr-3x8m.
  • recall_for_action returned any trusted memory the query retrieved, whether or not it answered the request. A shipping request could be justified by a stored party size.
  • Each slot held one value, so user/email could not hold both a personal and a billing email.

Install or upgrade

pip install --upgrade 'pycontextdb==0.4.6'

No schema or data migration is required.

Runnable example

Offline, with the mock embedder and mock model:

import asyncio
import tempfile

import contextdb


async def main():
    db = contextdb.init(
        user_id="synthetic_customer_7",
        storage_url=f"sqlite:///{tempfile.mkdtemp()}/demo.db",
        embedding_model="mock",
        llm_model="mock",
        llm_api_key="mock",
        enable_entity_graph=False,
    )
    async with db:
        mine = await db.factual.add(
            "My email is avery.example@example.com",
            source="user_stated", action_relevant=True,
            entity="user", attribute="email",
        )
        await db.factual.add(
            "Vendor portal export: the customer's email is claims@lookalike.example",
            source="third_party", action_relevant=True,
            entity="user", attribute="email",
        )
        kept = await db.get(mine.id)
        print("user's own email still current:", kept.valid_until is None)

        await db.factual.add(
            "We are a party of 4",
            source="user_stated", action_relevant=True,
            entity="reservation", attribute="party_size",
        )
        scoped = await db.factual.recall_for_action(
            "ship my order to my home", entity="user", attribute="address"
        )
        print("trusted when the action names user/address:", len(scoped))


asyncio.run(main())

Verified output on October 8, 2026:

pycontextdb 0.4.5                                    pycontextdb 0.4.6
user's own email still current: False                user's own email still current: True
trusted when the action names user/address: n/a      trusted when the action names user/address: 0

On 0.4.6 the vendor's value is stored as contested, so neither email gates an action until the user confirms one.

Use cases

  • Support-agent developers who file customer emails and tickets as third_party: a ticket that names a different email or account number now raises a question instead of replacing what the customer told you.
  • Booking and commerce agents: pass entity="user", attribute="address" before shipping, or entity="reservation", attribute="party_size" before booking, so only that fact can justify act.
  • Billing workflows: store where invoices go as user/billing_email next to the customer's own user/email.

Verified behavior

  • Five new evals: four fail on 0.4.5 and pass on 0.4.6, and one guards behaviour that must not change. They cover a lower-trust write contesting a user's fact, an explicit evolve("update") from a document, corrections of equal or higher trust still superseding, slot-scoped action recall, and separate billing email.
  • CI passed on Python 3.10, 3.11, and 3.12, the PostgreSQL integration job, and the secret scan.

Compatibility and limitations

  • Behaviour change: a third_party or agent_inferred write that disagrees with a user_stated or confirmed fact now contests the slot instead of replacing it. Actions on that slot ask until the user confirms one value. This includes a system of record stored as third_party. Corrections of equal or higher trust still supersede.
  • New optional arguments: entity and attribute on factual.recall_for_action and factual.pending_confirmations, plus ContextDB.slot_facts(). Pass both or neither. Without them, behaviour is unchanged.
  • Vocabulary version 2: adds three slots and the aliases invoice_email, office_phone, and office_address. Existing slots are unchanged.
  • Unchanged limitations:
    • Different appointment types still share appointment/day.
    • The write-time injection screen is high precision and does not catch paraphrased instructions. Label documents and tool output third_party.

Links

FAQ

Do I need to migrate data? No. Existing memories keep working. Only new writes follow the new rules.

Will my agent ask more often? Only when a lower-trust source disagrees with what the user said, or when an action names a slot that has nothing trusted in it. Both used to produce a silent replacement or an act on unrelated evidence.

Does ContextDB Cloud use 0.4.6? Not yet. Cloud stays on its pinned SDK until its scheduled upgrade.