@pentatonic-ai/ai-agent-sdk 0.10.20 → 0.10.22

package/dist/index.cjs

@@ -878,7 +878,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.20";
+var VERSION = "0.10.22";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/dist/index.js

@@ -847,7 +847,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.20";
+var VERSION = "0.10.22";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.10.20",
+  "version": "0.10.22",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory-engine-v2/compat/server.py

@@ -913,6 +913,34 @@ def _resolve_arenas(req: GraphQueryRequest) -> list[str]:
     return arenas
 
 
+# Decay access signal (RFC-decay-and-fusion Part B1): the Fusion Drive decay pass
+# ages salience by the most recent of (last_accessed, last_seen/asserted_at), so
+# without an access bump a frequently-retrieved memory still decays and can be
+# evicted. Bump last_accessed on the nodes a read returns so retrieval keeps them
+# alive. THROTTLED to once / _ACCESS_BUMP_THROTTLE per node (the UPDATE no-ops for
+# nodes touched recently) to bound write amplification on these hot read paths,
+# and BEST-EFFORT — a bump failure must never fail the read. `table` is always a
+# trusted literal (never user input).
+_ACCESS_BUMP_THROTTLE = "6 hours"
+
+
+async def _bump_last_accessed(conn, cur, table: str, ids: list[str]) -> None:
+    ids = [i for i in ids if i]
+    if not ids:
+        return
+    try:
+        await cur.execute(
+            f"UPDATE {table} SET last_accessed = NOW() "
+            f"WHERE id = ANY(%s) AND (last_accessed IS NULL "
+            f"OR last_accessed < NOW() - interval '{_ACCESS_BUMP_THROTTLE}')",
+            (ids,),
+        )
+        await conn.commit()
+    except Exception as e:  # noqa: BLE001 — never let the access bump break a read
+        await conn.rollback()
+        log.warning("last_accessed bump failed on %s: %s", table, e)
+
+
 @app.post("/entities")
 async def list_entities(req: GraphQueryRequest):
     """Filter entities by arena + optional type + optional name pattern.
@@ -930,10 +958,10 @@ async def list_entities(req: GraphQueryRequest):
         params.extend([pattern, pattern])
     sql = f"""
         SELECT id, arena, entity_type, canonical_name, aliases,
-               provenance_event_ids, attributes, last_seen
+               provenance_event_ids, attributes, salience, last_seen
           FROM entities
          WHERE {' AND '.join(conditions)}
-      ORDER BY last_seen DESC
+      ORDER BY salience DESC, last_seen DESC
          LIMIT %s
     """
     params.append(req.limit)
@@ -941,6 +969,7 @@ async def list_entities(req: GraphQueryRequest):
         async with conn.cursor() as cur:
             await cur.execute(sql, params)
             rows = await cur.fetchall()
+            await _bump_last_accessed(conn, cur, "entities", [r["id"] for r in rows])
     return {"results": [dict(r) for r in rows]}
 
 
@@ -977,10 +1006,10 @@ async def list_facts(req: GraphQueryRequest):
         SELECT f.id, f.arena, f.category, f.predicate, f.statement,
                f.subject_entity_id, f.object_entity_id,
                f.confidence, f.stage, f.asserted_at,
-               f.provenance_event_ids
+               f.salience, f.provenance_event_ids
           FROM facts f
          WHERE {' AND '.join(conditions)}
-      ORDER BY f.asserted_at DESC
+      ORDER BY f.salience DESC, f.asserted_at DESC
          LIMIT %s
     """
     params.append(req.limit)
@@ -988,6 +1017,7 @@ async def list_facts(req: GraphQueryRequest):
         async with conn.cursor() as cur:
             await cur.execute(sql, params)
             rows = await cur.fetchall()
+            await _bump_last_accessed(conn, cur, "facts", [r["id"] for r in rows])
     return {"results": [dict(r) for r in rows]}
 
 
@@ -1013,13 +1043,13 @@ async def list_relationships(req: GraphQueryRequest):
                r.from_entity_id, r.to_entity_id,
                ef.canonical_name AS from_name,
                et.canonical_name AS to_name,
-               r.first_seen, r.last_seen,
+               r.first_seen, r.last_seen, r.salience,
                r.provenance_event_ids
           FROM relationships r
           JOIN entities ef ON ef.id = r.from_entity_id
           JOIN entities et ON et.id = r.to_entity_id
          WHERE {' AND '.join(conditions)}
-      ORDER BY r.last_seen DESC
+      ORDER BY r.salience DESC, r.last_seen DESC
          LIMIT %s
     """
     params.append(req.limit)
@@ -1027,6 +1057,7 @@ async def list_relationships(req: GraphQueryRequest):
         async with conn.cursor() as cur:
             await cur.execute(sql, params)
             rows = await cur.fetchall()
+            await _bump_last_accessed(conn, cur, "relationships", [r["id"] for r in rows])
     return {"results": [dict(r) for r in rows]}
 
 

package/packages/memory-engine-v2/extractor-async/test_org_domain.py

@@ -327,3 +327,45 @@ def test_external_id_keys_a_domainless_record_node() -> None:
     assert worker.entity_id("arena1", "org", ext) != worker.entity_id(
         "arena1", "org", "Acme Corp"
     )
+
+
+# ----------------------------------------------------------------------
+# _person_email_domain — person email/domain stamped as a node attribute
+# (SEE-192). Pure helper; the upsert SQL that consumes it is covered by the
+# engine import check, same posture as the org-domain stamp above.
+# ----------------------------------------------------------------------
+
+def test_person_email_domain_plain() -> None:
+    assert worker._person_email_domain(
+        ["Johann Boedecker", "johann@pentatonic.com"]
+    ) == ("johann@pentatonic.com", "pentatonic.com")
+
+
+def test_person_email_domain_lowercases() -> None:
+    assert worker._person_email_domain(["J@PENTATONIC.com"]) == (
+        "j@pentatonic.com",
+        "pentatonic.com",
+    )
+
+
+def test_person_email_domain_none_without_an_email() -> None:
+    # name-only aliases (a fragmented person with no email) → nothing to stamp.
+    assert worker._person_email_domain(["Johann Boedecker", "Bödecker, Johann"]) == (
+        None,
+        None,
+    )
+    assert worker._person_email_domain([]) == (None, None)
+
+
+def test_person_email_domain_only_bare_addresses() -> None:
+    # mirrors the id-key selection: a display-name form ("X <a@b.com>", has a
+    # space) is NOT treated as the person's bare address — graph aliases carry
+    # the bare email, and this keeps the attribute aligned with person_id_key.
+    assert worker._person_email_domain(["Bob Smith <bob@lego.com>"]) == (None, None)
+
+
+def test_person_email_domain_subdomain_preserved() -> None:
+    assert worker._person_email_domain(["a@mail.acme.co.uk"]) == (
+        "a@mail.acme.co.uk",
+        "mail.acme.co.uk",
+    )

package/packages/memory-engine-v2/extractor-async/worker.py

@@ -1098,6 +1098,18 @@ def _domain_of(value: str) -> str | None:
     return m.group(1).lower() if m else None
 
 
+def _person_email_domain(aliases: list[str]) -> tuple[str | None, str | None]:
+    """A person's own email (first alias that looks like a bare address) and its
+    domain, for stamping as queryable node attributes (SEE-192). Returns
+    `(lowercased_email, domain)` or `(None, None)`. Callers run this AFTER the
+    email-alias guard, so a surviving address is the person's own — not a
+    bystander. Mirrors the org-domain stamp; reuses `_domain_of`."""
+    email = next((a for a in aliases if a and "@" in a and " " not in a), None)
+    if not email:
+        return None, None
+    return email.strip().lower(), _domain_of(email)
+
+
 def _bare_domain(value: str) -> str | None:
     """Normalise a structured domain field to a bare host — 'acme.com' from
     'Acme.com', 'https://www.acme.com/about', etc. Used for system-of-record
@@ -1416,6 +1428,21 @@ def upsert_entities(
                 if subject_ext_id not in aliases:
                     aliases.append(subject_ext_id)
                 attrs_patch["external_id"] = subject_ext_id
+            # Person email/domain as a QUERYABLE node attribute (SEE-192). The
+            # email already mints the id (person_id_key) and survives the alias
+            # guard above, but was never persisted as a discrete attribute — so
+            # retrieval / context-aware mention resolution had to dig it out of
+            # the aliases array (text-search, not indexed) and 0/37,648 person
+            # nodes carried `attributes.email`/`domain`. Stamp it (lowercased) +
+            # its domain, mirroring the org-domain stamp, so a person node is
+            # directly matchable by email/domain. Merge-only (`|| jsonb`); the
+            # guard already dropped bystander emails, so this is the person's own.
+            if etype == "person":
+                _pemail, _pdomain = _person_email_domain(aliases)
+                if _pemail:
+                    attrs_patch["email"] = _pemail
+                    if _pdomain:
+                        attrs_patch["domain"] = _pdomain
             attrs_update = json.dumps(attrs_patch)
 
             # Sort (don't `list(set(...))`) so lock acquisition order

package/packages/memory-engine-v2/extractor-sync/server.py

@@ -36,6 +36,8 @@ from entity_id import entity_id, normalize_surface_form, person_id_key  # noqa:
 # Source-time parsing — byte-identical copy in extractor-async (source_time.py).
 from source_time import event_source_time
 
+import json
+
 import psycopg
 import psycopg.rows
 from fastapi import FastAPI, HTTPException
@@ -270,6 +272,18 @@ def _person_entity(
         if a:
             aliases_set.add(a)
 
+    # Email/domain as a QUERYABLE node attribute (SEE-192). The sync pass keys
+    # the node on the ENVELOPE email (the most reliable source — not LLM-
+    # promoted), so stamp it (lowercased) + its domain here so a person node is
+    # directly matchable by email/domain instead of only via the aliases array.
+    attrs: dict[str, str] = {}
+    if email:
+        em = email.strip().lower()
+        attrs["email"] = em
+        dom = em.rsplit("@", 1)[-1] if "@" in em else ""
+        if dom and "." in dom and " " not in dom:
+            attrs["domain"] = dom
+
     return {
         "id": _entity_id(req.arena, "person", id_key),
         "arena": req.arena,
@@ -279,6 +293,7 @@ def _person_entity(
         "provenance_event_ids": [event_id],
         "participant_set": req.attributes.get("participant_set", [req.arena]),
         "disclosure_class": req.attributes.get("disclosure_class", "private"),
+        "attributes": attrs,
     }
 
 
@@ -550,10 +565,10 @@ async def _upsert_entities(
                 INSERT INTO entities (
                   id, arena, entity_type, canonical_name, aliases,
                   provenance_event_ids, participant_set, disclosure_class,
-                  first_seen, last_seen, salience
+                  first_seen, last_seen, salience, attributes
                 ) VALUES (
                   %s, %s, %s, %s, %s, %s, %s, %s::disclosure_class,
-                  COALESCE(%s, NOW()), COALESCE(%s, NOW()), %s
+                  COALESCE(%s, NOW()), COALESCE(%s, NOW()), %s, %s::jsonb
                 )
                 ON CONFLICT (id) DO UPDATE SET
                   aliases = (
@@ -562,6 +577,9 @@ async def _upsert_entities(
                   provenance_event_ids = (
                     SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
                   ),
+                  -- merge the email/domain hard key (no-op for the `{}` default
+                  -- on entity types that don't stamp it); never clobbers.
+                  attributes = entities.attributes || EXCLUDED.attributes,
                   salience = GREATEST(entities.salience, EXCLUDED.salience),
                   last_seen = GREATEST(entities.last_seen, EXCLUDED.last_seen),
                   first_seen = LEAST(entities.first_seen, EXCLUDED.first_seen)
@@ -569,7 +587,8 @@ async def _upsert_entities(
                 (e["id"], e["arena"], e["entity_type"], e["canonical_name"],
                  e["aliases"], e["provenance_event_ids"],
                  e["participant_set"], e["disclosure_class"],
-                 event_time, event_time, _sal),
+                 event_time, event_time, _sal,
+                 json.dumps(e.get("attributes") or {})),
             )