Repository navigation
pycontextdb 0.4.7: complete forgetting, no plaintext PII at rest, exact-identifier recall
Complete forgetting, no plaintext PII at rest, and exact-identifier recall
pycontextdb 0.4.7 fixes three privacy and correctness gaps in the open-source ContextDB SDK and adds exact-identifier recall:
- Forgetting a user now also removes what they added to shared entities.
- Encrypt mode no longer writes plaintext emails or phone numbers to disk.
- Order numbers and SKUs are found even when vector similarity misses them.
What was wrong in 0.4.6:
forget_userdeleted a user's memories but left the attributes their text had merged into shared entities, andverify_forgottenstill returned true.- Slot values, kept only for comparing facts, were taken from the original utterance. In encrypt mode the content was redacted and the annotations encrypted, but the slot value still held the plaintext email or phone number.
- Two emails saved with
add_fastboth read[EMAIL]after redaction, so consolidation treated the second as a repeat and dropped it. - A query for an exact identifier depended on vector similarity alone, and a strict relevance floor could hide the right memory.
- A dentist appointment and a haircut appointment shared one slot and could replace or merge with each other.
- The README quoted v0.1.0 performance (3.4 ms search). The current build measures about 11 ms p50 at 1,000 memories with the mock embedder.
Install or upgrade
pip install --upgrade 'pycontextdb==0.4.7'No migration is required. A new table for entity attribute sources is created on first use.
Runnable example
Offline, with the mock embedder and mock model:
import asyncio
import glob
import json
import tempfile
import contextdb
from contextdb.core.policy import TrustPolicy
from contextdb.utils.llm import MockLLM
async def main():
folder = tempfile.mkdtemp()
db = contextdb.init(
user_id="synthetic_customer_7",
storage_url=f"sqlite:///{folder}/demo.db",
embedding_model="mock", llm_model="mock", llm_api_key="mock",
enable_entity_graph=False,
pii_action="encrypt", pii_encryption_key="synthetic-demo-key",
trust_policy=TrustPolicy(relevance_floor=0.99),
)
async with db:
await db.factual.add(
"My email is avery.example@example.com",
source="user_stated", action_relevant=True,
entity="user", attribute="email",
)
for n in range(40):
await db.factual.add(f"Order ORD-{48000 + n} shipped on Monday", source="user_stated")
await db.factual.add("Order ORD-48213 was refunded on Friday", source="user_stated")
hits = await db.search("what happened with ORD-48213")
print("order found through a strict floor:", [h.content for h in hits][:1])
stored = b"".join(open(p, "rb").read() for p in glob.glob(f"{folder}/demo.db*"))
print("plaintext email on disk:", b"avery.example@example.com" in stored)
shared = contextdb.init(
tenant_id="synthetic-org",
storage_url=f"sqlite:///{folder}/shared.db",
embedding_model="mock", llm_model="mock", llm_api_key="mock",
enable_entity_graph=True,
)
shared._llm = MockLLM(responses={
"Friday calls": '{"entities": [{"name": "Acme", "type": "ORG", "attributes": {"plan": "gold"}}]}',
"Escalation": '{"entities": [{"name": "Acme", "type": "ORG", "attributes": {"region": "west"}}]}',
})
async with shared:
await shared.factual.add("Prefers Friday calls about Acme.", source="user_stated", user_id="alice")
await shared.factual.add("Escalation contact for Acme.", source="user_stated", user_id="bob")
await shared.forget_user("alice")
cursor = await shared._store._require_conn().execute("SELECT attributes FROM entities")
print("shared entity after forgetting alice:", [json.loads(r["attributes"]) for r in await cursor.fetchall()])
asyncio.run(main())Verified output on October 12, 2026:
pycontextdb 0.4.6
order found through a strict floor: []
plaintext email on disk: True
shared entity after forgetting alice: [{'plan': 'gold', 'region': 'west'}]
pycontextdb 0.4.7
order found through a strict floor: ['Order ORD-48213 was refunded on Friday']
plaintext email on disk: False
shared entity after forgetting alice: [{'region': 'west'}]
Use cases
- Privacy and compliance engineers handling erasure requests:
forget_usernow also removes the user's contributions to shared entities, andverify_forgottenchecks for them. - Teams running encrypt mode for regulated data: no plaintext email, phone number, or opt-in address reaches the database file.
- Support and commerce agents that look up orders: "what happened with ORD-48213" finds that order even among many similar ones.
- Scheduling agents: a customer's dentist and haircut appointments stay separate facts.
Verified behavior
- Each fix has an eval that fails on 0.4.6 and passes on 0.4.7. The PII eval scans every byte of the database files for the test email and address.
- CI passed on Python 3.10, 3.11, and 3.12, the PostgreSQL integration job, and the secret scan. Entity cleanup and identifier search were also checked by hand against PostgreSQL 16.
Compatibility and limitations
- New optional setting:
pii_detect_names_and_addresses(default off). Redacted names and addresses are hidden from the agent too. - New store method:
BaseStore.search_textreturns nothing by default, so custom stores keep working. - Fingerprinted slot values: slot values that contain PII are now fingerprints. A value stored before 0.4.7 compares as different from the same value written now, so the next write supersedes it once.
- Attributes merged before 0.4.7 have no recorded source. They stay until their entity is no longer referenced by any memory.
- Narrow identifier matching: identifier recall only uses tokens of three or more characters that contain a digit. Names without digits still rely on vector similarity.
- Precision-first name detection: it needs a cue such as "my name is" and misses names without one.
Links
FAQ
Do I need to migrate? No. A new table is created automatically, and existing data keeps working.
Will my agent lose access to addresses? Only if you turn on pii_detect_names_and_addresses. It is off by default.
Does ContextDB Cloud use 0.4.7? Not yet. Cloud stays on its pinned SDK until its scheduled upgrade.