@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/infrastructure/in_memory_store.py

@@ -0,0 +1,1008 @@
+"""In-memory adapter used for tests, fixtures, and CLI test mode."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from typing import Iterable
+
+from people_network_memory.domain.models import (
+    AttributedClaim,
+    ContactMethod,
+    DirectFact,
+    EducationRecord,
+    Evidence,
+    FollowUpTask,
+    IdentityCandidate,
+    PersonMemoryRecord,
+    PersonRef,
+    RecordInteractionResult,
+    RetrievalItem,
+    ReviewItem,
+    SensitivityLabel,
+    SocialInteraction,
+    WorkHistoryRecord,
+)
+from people_network_memory.infrastructure.retrieval_intent import (
+    is_follow_up_query,
+    mentioned_query_target,
+    person_is_only_mentioned_target,
+    text_answers_mentioned_query,
+)
+from people_network_memory.ports.errors import PersistenceError
+from people_network_memory.infrastructure.id_generator import SequentialIdGenerator
+
+
+ASCII_TOKEN_RE = re.compile(r"[a-z0-9_]+", flags=re.IGNORECASE)
+CJK_RUN_RE = re.compile(r"[\u4e00-\u9fff]+")
+CJK_STOPWORDS = {"的", "了", "和", "与", "在"}
+CJK_ALIAS_LEFT_BOUNDARY = set("叫找查问和与跟给向说提约帮为")
+CJK_ALIAS_RIGHT_BOUNDARY = set("是的在有做聊说问要还关喜哪什现吗呢呀吧了")
+
+
+class InMemoryPeopleStore:
+    def __init__(self) -> None:
+        self._ids = SequentialIdGenerator()
+        self.people: dict[str, PersonMemoryRecord] = {}
+        self.review_items: list[ReviewItem] = []
+        self.interactions: dict[str, SocialInteraction] = {}
+        self.evidence: dict[str, Evidence] = {}
+
+    @property
+    def id_generator(self) -> SequentialIdGenerator:
+        return self._ids
+
+    def find_identity_candidates(self, ref: PersonRef) -> list[IdentityCandidate]:
+        candidates: list[IdentityCandidate] = []
+        ref_names = [_norm(ref.label), *[_norm(alias) for alias in ref.aliases]]
+        ref_names = [name for name in ref_names if name]
+        explicit_name_matches = _explicit_name_match_ids(self.people.values(), ref_names)
+        for person in self.people.values():
+            labels = [person.display_name, *person.aliases]
+            if not explicit_name_matches:
+                labels.extend(_cjk_name_aliases(person.display_name))
+            normalized_labels = [_norm(label) for label in labels if _norm(label)]
+            exact_identifier = False
+            for contact in person.contacts:
+                if ref.email and contact.kind == "email" and _norm(contact.value) == _norm(ref.email):
+                    exact_identifier = True
+                if ref.phone and contact.kind == "phone" and _digits(contact.value) == _digits(ref.phone):
+                    exact_identifier = True
+            name_score = max(
+                (
+                    _name_score(ref_name, candidate_name)
+                    for ref_name in ref_names
+                    for candidate_name in normalized_labels
+                ),
+                default=0.0,
+            )
+            exact_name_match = _norm(ref.label) in normalized_labels
+            company_score = 0.0
+            if ref.company_hint:
+                company_score = max(
+                    (
+                        0.2
+                        for work in person.work_history
+                        if _norm(ref.company_hint) in _norm(work.organization)
+                    ),
+                    default=0.0,
+                )
+            score = 1.0 if exact_identifier else min(0.95, name_score + company_score)
+            if exact_identifier or score >= 0.45:
+                candidates.append(
+                    IdentityCandidate(
+                        person_id=person.person_id,
+                        display_name=person.display_name,
+                        score=score,
+                        evidence=labels,
+                        exact_identifier_match=exact_identifier,
+                        exact_name_match=exact_name_match,
+                    )
+                )
+        return sorted(candidates, key=lambda item: item.score, reverse=True)[:5]
+
+    def save_interaction(
+        self, interaction: SocialInteraction, identity_map: dict[str, str | None]
+    ) -> RecordInteractionResult:
+        now = datetime.now(timezone.utc)
+        interaction_id = self._new_unique_id("interaction", self.interactions)
+        evidence = Evidence(
+            evidence_id=self._new_unique_id("evidence", self.evidence),
+            source_text=interaction.source_text,
+            recorded_at=interaction.occurred_at or now,
+        )
+        self.evidence[evidence.evidence_id] = evidence
+        self.interactions[interaction_id] = interaction
+        created: list[str] = []
+        updated: list[str] = []
+        all_refs = list(_iter_refs(interaction))
+        ref_to_id: dict[str, str] = {}
+        for ref in all_refs:
+            key = _ref_key(ref)
+            if key in ref_to_id:
+                continue
+            person_id = identity_map.get(key) or ref.person_id
+            if not person_id:
+                person_id = self._create_person(ref, evidence)
+                created.append(person_id)
+            elif person_id not in self.people:
+                person_id = self._create_person(ref, evidence, explicit_id=person_id)
+                created.append(person_id)
+            else:
+                updated.append(person_id)
+                self._append_unique_evidence(person_id, evidence)
+                self._merge_aliases(self.people[person_id], [ref.label, *ref.aliases])
+            ref_to_id[key] = person_id
+        attached_person_ids: set[str] = set()
+        for ref in all_refs:
+            person_id = ref_to_id[_ref_key(ref)]
+            if person_id in attached_person_ids:
+                continue
+            attached_person_ids.add(person_id)
+            record = self.people[person_id]
+            record.interactions.append(interaction)
+            self._append_unique_evidence(person_id, evidence)
+        self._attach_interaction_details(interaction, ref_to_id)
+        self._complete_matching_follow_ups(interaction, ref_to_id)
+        return RecordInteractionResult(
+            interaction_id=interaction_id,
+            created_people=sorted(set(created)),
+            updated_people=sorted(set(updated)),
+            person_ref_map=ref_to_id,
+            evidence=[evidence],
+        )
+
+    def get_person_memory(self, person_id: str) -> PersonMemoryRecord | None:
+        return self.people.get(person_id)
+
+    def find_person_memory_by_name(self, name: str) -> list[PersonMemoryRecord]:
+        normalized = _norm(name)
+        if not normalized:
+            return []
+        matches: list[PersonMemoryRecord] = []
+        explicit_name_matches = _explicit_name_match_ids(
+            self.people.values(), [normalized]
+        )
+        for person in self.people.values():
+            labels = [person.display_name, *person.aliases]
+            if not explicit_name_matches:
+                labels.extend(_cjk_name_aliases(person.display_name))
+            if any(_norm(label) == normalized for label in labels):
+                matches.append(person)
+        return sorted(matches, key=lambda person: person.display_name.casefold())
+
+    def merge_people(
+        self, *, source_person_id: str, target_person_id: str, note: str | None = None
+    ) -> PersonMemoryRecord:
+        if source_person_id == target_person_id:
+            raise PersistenceError("source_person_id and target_person_id must differ")
+        source = self.people.get(source_person_id)
+        target = self.people.get(target_person_id)
+        if source is None:
+            raise PersistenceError(f"Source person not found: {source_person_id}")
+        if target is None:
+            raise PersistenceError(f"Target person not found: {target_person_id}")
+
+        self._merge_aliases(target, [source.display_name, *source.aliases])
+        _extend_unique(target.work_history, source.work_history)
+        _extend_unique(target.education, source.education)
+        _extend_unique(target.interests, source.interests)
+        _extend_unique(target.important_dates, source.important_dates)
+        _extend_unique(target.contacts, source.contacts)
+        _extend_unique(target.preferences, source.preferences)
+        _extend_unique(target.direct_facts, source.direct_facts)
+        _extend_unique(target.attributed_claims, source.attributed_claims)
+        _extend_unique(target.relationships, source.relationships)
+        _extend_unique(target.follow_ups, source.follow_ups)
+        _extend_unique(target.evidence, source.evidence)
+
+        moved_interactions = list(source.interactions)
+        for interaction in moved_interactions:
+            _remap_interaction(interaction, source_person_id, target_person_id)
+        _extend_unique(target.interactions, moved_interactions)
+        for interaction in self.interactions.values():
+            _remap_interaction(interaction, source_person_id, target_person_id)
+        _remap_person_record(target, source_person_id, target_person_id)
+        del self.people[source_person_id]
+        return target
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 10,
+        include_sensitive: bool = False,
+        mode: str = "recall",
+    ) -> list[RetrievalItem]:
+        query_tokens = _tokens(query)
+        mention_target = mentioned_query_target(query)
+        follow_up_intent = is_follow_up_query(query)
+        explicit_query_person_ids = (
+            set()
+            if mention_target
+            else _explicit_query_alias_match_ids(self.people.values(), query)
+        )
+        ambiguous_name_person_ids = (
+            set()
+            if (
+                explicit_query_person_ids
+                or mention_target
+                or follow_up_intent
+            )
+            else _ambiguous_query_display_name_match_ids(self.people.values(), query)
+        )
+        items: list[RetrievalItem] = []
+        for person in self.people.values():
+            if (
+                explicit_query_person_ids
+                and person.person_id not in explicit_query_person_ids
+            ):
+                continue
+            if (
+                ambiguous_name_person_ids
+                and person.person_id not in ambiguous_name_person_ids
+            ):
+                continue
+            items.extend(
+                self._person_items(
+                    person,
+                    query_tokens,
+                    include_sensitive,
+                    mode,
+                    mention_target=mention_target,
+                    follow_up_intent=follow_up_intent,
+                    profile_only=bool(ambiguous_name_person_ids),
+                )
+            )
+        return sorted(items, key=lambda item: item.score, reverse=True)[:limit]
+
+    def add_review_item(self, item: ReviewItem) -> None:
+        self.review_items.append(item)
+
+    def list_review_items(self, *, status: str | None = None) -> list[ReviewItem]:
+        if status is None:
+            return list(self.review_items)
+        return [item for item in self.review_items if item.status == status]
+
+    def update_review_item(self, item: ReviewItem) -> ReviewItem:
+        for index, existing in enumerate(self.review_items):
+            if existing.review_id == item.review_id:
+                self.review_items[index] = item
+                return item
+        raise PersistenceError(f"Review item not found: {item.review_id}")
+
+    def export_data(self) -> dict[str, object]:
+        return {
+            "people": [person.model_dump(mode="json") for person in self.people.values()],
+            "review_items": [item.model_dump(mode="json") for item in self.review_items],
+            "interactions": [
+                interaction.model_dump(mode="json")
+                for interaction in self.interactions.values()
+            ],
+        }
+
+    def _create_person(
+        self, ref: PersonRef, evidence: Evidence, *, explicit_id: str | None = None
+    ) -> str:
+        person_id = explicit_id or self._new_unique_id("person", self.people)
+        if person_id in self.people:
+            raise PersistenceError(f"Person id already exists: {person_id}")
+        aliases = [alias for alias in ref.aliases if alias != ref.label]
+        self.people[person_id] = PersonMemoryRecord(
+            person_id=person_id,
+            display_name=ref.label,
+            aliases=aliases,
+            evidence=[evidence],
+        )
+        return person_id
+
+    def _new_unique_id(self, prefix: str, existing: object) -> str:
+        if isinstance(existing, dict):
+            existing_ids = set(existing)
+        else:
+            existing_ids = set(existing)
+        while True:
+            item_id = self._ids.new_id(prefix)
+            if item_id not in existing_ids:
+                return item_id
+
+    def _append_unique_evidence(self, person_id: str, evidence: Evidence) -> None:
+        record = self.people[person_id]
+        if all(item.evidence_id != evidence.evidence_id for item in record.evidence):
+            record.evidence.append(evidence)
+
+    def _merge_aliases(self, record: PersonMemoryRecord, aliases: list[str]) -> None:
+        for alias in aliases:
+            alias = alias.strip()
+            if alias and alias != record.display_name and alias not in record.aliases:
+                record.aliases.append(alias)
+
+    def _attach_interaction_details(
+        self, interaction: SocialInteraction, ref_to_id: dict[str, str]
+    ) -> None:
+        for fact in interaction.direct_facts:
+            person_id = ref_to_id.get(_ref_key(fact.subject))
+            if person_id:
+                resolved_fact = fact.model_copy(
+                    update={"subject": self._resolved_ref(fact.subject, ref_to_id)}
+                )
+                self.people[person_id].direct_facts.append(resolved_fact)
+                self._derive_profile_fact(self.people[person_id], resolved_fact)
+        for claim in interaction.attributed_claims:
+            resolved_claim = claim.model_copy(
+                update={
+                    "speaker": (
+                        self._resolved_ref(claim.speaker, ref_to_id)
+                        if claim.speaker
+                        else None
+                    ),
+                    "subject": (
+                        self._resolved_ref(claim.subject, ref_to_id)
+                        if claim.subject
+                        else None
+                    ),
+                }
+            )
+            if claim.subject:
+                person_id = ref_to_id.get(_ref_key(claim.subject))
+                if person_id:
+                    self.people[person_id].attributed_claims.append(resolved_claim)
+            if claim.speaker:
+                speaker_id = ref_to_id.get(_ref_key(claim.speaker))
+                if (
+                    speaker_id
+                    and resolved_claim not in self.people[speaker_id].attributed_claims
+                ):
+                    self.people[speaker_id].attributed_claims.append(resolved_claim)
+        for follow_up in interaction.follow_ups:
+            resolved_follow_up = follow_up.model_copy(
+                update={
+                    "related_people": [
+                        self._resolved_ref(ref, ref_to_id)
+                        for ref in follow_up.related_people
+                    ]
+                }
+            )
+            for ref in follow_up.related_people:
+                person_id = ref_to_id.get(_ref_key(ref))
+                if person_id:
+                    self.people[person_id].follow_ups.append(resolved_follow_up)
+        for relationship in interaction.relationships:
+            resolved_relationship = relationship.model_copy(
+                update={
+                    "source": self._resolved_ref(relationship.source, ref_to_id),
+                    "target": self._resolved_ref(relationship.target, ref_to_id),
+                }
+            )
+            for ref in [relationship.source, relationship.target]:
+                person_id = ref_to_id.get(_ref_key(ref))
+                if person_id:
+                    self.people[person_id].relationships.append(resolved_relationship)
+        for topic in interaction.topics:
+            for participant in interaction.participants:
+                person_id = ref_to_id.get(_ref_key(participant.person))
+                if person_id and topic not in self.people[person_id].interests:
+                    self.people[person_id].interests.append(topic)
+
+    def _complete_matching_follow_ups(
+        self, interaction: SocialInteraction, ref_to_id: dict[str, str]
+    ) -> None:
+        if not _looks_like_follow_up_completion(interaction.source_text):
+            return
+        candidate_person_ids = {
+            person_id
+            for ref in _iter_refs(interaction)
+            for person_id in [ref_to_id.get(_ref_key(ref))]
+            if person_id
+        }
+        for person_id in candidate_person_ids:
+            record = self.people.get(person_id)
+            if record is None:
+                continue
+            for index, follow_up in enumerate(record.follow_ups):
+                if not _completion_matches_follow_up(interaction.source_text, follow_up):
+                    continue
+                record.follow_ups[index] = follow_up.model_copy(update={"status": "done"})
+            _mark_matching_follow_ups_done(record.interactions, interaction.source_text)
+        _mark_matching_follow_ups_done(self.interactions.values(), interaction.source_text)
+
+    def _resolved_ref(
+        self, ref: PersonRef, ref_to_id: dict[str, str]
+    ) -> PersonRef:
+        person_id = ref_to_id.get(_ref_key(ref))
+        record = self.people.get(person_id or "")
+        if record is None:
+            return ref
+        aliases = [alias for alias in record.aliases if alias != record.display_name]
+        return ref.model_copy(update={"label": record.display_name, "aliases": aliases})
+
+    def _derive_profile_fact(self, record: PersonMemoryRecord, fact: DirectFact) -> None:
+        predicate = fact.predicate.lower()
+        value = fact.value.strip()
+        if predicate in {"works_at", "worked_at", "work", "current_job"}:
+            work = WorkHistoryRecord(
+                organization=value,
+                role=_metadata_str(fact.metadata, "role"),
+                is_current=predicate != "worked_at",
+            )
+            _append_unique(record.work_history, work)
+            return
+        if predicate in {"studied_at", "school", "education"}:
+            education = EducationRecord(
+                school=value,
+                degree=_metadata_str(fact.metadata, "degree"),
+                major=_metadata_str(fact.metadata, "major"),
+            )
+            _append_unique(record.education, education)
+            return
+        if predicate in {"email", "phone", "linkedin", "wechat"}:
+            contact = ContactMethod(kind=predicate, value=value)
+            _append_unique(record.contacts, contact)
+            return
+        if predicate in {"interest", "interested_in", "hobby"} and value not in record.interests:
+            record.interests.append(value)
+        if predicate in {"preference", "likes"} and value not in record.preferences:
+            record.preferences.append(value)
+
+    def _person_items(
+        self,
+        person: PersonMemoryRecord,
+        query_tokens: set[str],
+        include_sensitive: bool,
+        mode: str,
+        *,
+        mention_target: str | None,
+        follow_up_intent: bool,
+        profile_only: bool = False,
+    ) -> list[RetrievalItem]:
+        candidates: list[tuple[str, str, str, list[SensitivityLabel], bool]] = []
+        if not follow_up_intent and not mention_target:
+            candidates.append(("person", person.display_name, person.display_name, [], False))
+        profile_summary = _profile_summary_text(person)
+        if profile_summary and not follow_up_intent and not mention_target:
+            candidates.append(
+                (
+                    "fact",
+                    f"Profile summary for {person.display_name}",
+                    profile_summary,
+                    [],
+                    False,
+                )
+            )
+        for interaction in person.interactions:
+            if mention_target:
+                mentioned_pairs = [
+                    (
+                        mention.person.label,
+                        mention.mentioned_by.label if mention.mentioned_by else None,
+                    )
+                    for mention in interaction.mentioned_people
+                ]
+                if person_is_only_mentioned_target(
+                    person_label=person.display_name,
+                    target_label=mention_target,
+                    mentioned_pairs=mentioned_pairs,
+                ):
+                    continue
+                if not text_answers_mentioned_query(interaction.source_text, mention_target):
+                    continue
+            if follow_up_intent:
+                continue
+            interaction_sensitivity = _interaction_sensitivity(interaction)
+            candidates.append(
+                (
+                    "interaction",
+                    f"Interaction with {person.display_name}",
+                    interaction.source_text,
+                    interaction_sensitivity,
+                    False,
+                )
+            )
+        for fact in person.direct_facts:
+            if follow_up_intent or mention_target:
+                continue
+            candidates.append(
+                (
+                    "fact",
+                    f"{person.display_name}: {fact.predicate}",
+                    f"{fact.subject.label} {fact.predicate} {fact.value}",
+                    fact.sensitivity,
+                    False,
+                )
+            )
+        for claim in person.attributed_claims:
+            if follow_up_intent:
+                continue
+            if mention_target and not text_answers_mentioned_query(claim.claim_text, mention_target):
+                continue
+            candidates.append(
+                (
+                    "claim",
+                    f"Claim involving {person.display_name}",
+                    claim.claim_text,
+                    claim.sensitivity,
+                    True,
+                )
+            )
+        for relationship in person.relationships:
+            if follow_up_intent or mention_target:
+                continue
+            candidates.append(
+                (
+                    "fact",
+                    f"Relationship involving {person.display_name}",
+                    _relationship_text(relationship),
+                    relationship.sensitivity,
+                    False,
+                )
+            )
+        for follow_up in person.follow_ups:
+            if follow_up.status != "open":
+                continue
+            if mention_target:
+                continue
+            candidates.append(
+                (
+                    "follow_up",
+                    f"Follow-up for {person.display_name}",
+                    follow_up.description,
+                    follow_up.sensitivity,
+                    False,
+                )
+            )
+        if profile_only:
+            candidates = [
+                candidate
+                for candidate in candidates
+                if candidate[0] == "fact" and candidate[1].startswith("Profile summary")
+            ]
+        items: list[RetrievalItem] = []
+        for kind, title, text, sensitivity, secondhand in candidates:
+            if _blocked_by_sensitivity(sensitivity, include_sensitive):
+                continue
+            if kind == "person" and not query_tokens.issubset(_tokens(person.display_name)):
+                continue
+            score = _score(query_tokens, text, person.display_name)
+            if kind == "follow_up" and follow_up_intent:
+                score += 2.0
+            if title.startswith("Profile summary") and query_tokens.issubset(_tokens(text)):
+                score += 2.0
+            if mention_target and text_answers_mentioned_query(text, mention_target):
+                score += 1.5
+            if mode == "brief" and kind in {"interaction", "follow_up", "claim"}:
+                score += 0.25
+            if score <= 0:
+                continue
+            items.append(
+                RetrievalItem(
+                    item_id=f"{person.person_id}:{kind}:{abs(hash(text))}",
+                    kind=kind,  # type: ignore[arg-type]
+                    title=title,
+                    matched_text=text,
+                    score=score,
+                    why_matched="Matched query terms and related person context.",
+                    person_ids=[person.person_id],
+                    sensitivity=sensitivity,
+                    evidence=_result_evidence(person, include_sensitive),
+                    is_secondhand=secondhand,
+                )
+            )
+        return items
+
+
+def _iter_refs(interaction: SocialInteraction) -> Iterable[PersonRef]:
+    for participant in interaction.participants:
+        yield participant.person
+    for mentioned in interaction.mentioned_people:
+        yield mentioned.person
+        if mentioned.mentioned_by:
+            yield mentioned.mentioned_by
+    for claim in interaction.attributed_claims:
+        if claim.speaker:
+            yield claim.speaker
+        if claim.subject:
+            yield claim.subject
+    for fact in interaction.direct_facts:
+        yield fact.subject
+    for follow_up in interaction.follow_ups:
+        yield from follow_up.related_people
+    for relationship in interaction.relationships:
+        yield relationship.source
+        yield relationship.target
+
+
+def _ref_key(ref: PersonRef) -> str:
+    return ref.person_id or ref.email or ref.phone or ref.label
+
+
+def _norm(value: str | None) -> str:
+    return (value or "").strip().lower()
+
+
+def _digits(value: str | None) -> str:
+    return re.sub(r"\D+", "", value or "")
+
+
+def _name_score(ref_name: str, candidate_name: str) -> float:
+    if not ref_name or not candidate_name:
+        return 0.0
+    if ref_name == candidate_name:
+        return 0.9
+    if ref_name in candidate_name or candidate_name in ref_name:
+        return 0.65
+    ref_parts = set(ref_name.split())
+    candidate_parts = set(candidate_name.split())
+    if ref_parts & candidate_parts:
+        return 0.5
+    return 0.0
+
+
+def _explicit_name_match_ids(
+    people: Iterable[PersonMemoryRecord], ref_names: list[str]
+) -> set[str]:
+    ref_name_set = {name for name in ref_names if name}
+    if not ref_name_set:
+        return set()
+    return {
+        person.person_id
+        for person in people
+        if any(
+            _norm(label) in ref_name_set
+            for label in [person.display_name, *person.aliases]
+        )
+    }
+
+
+def _explicit_query_alias_match_ids(
+    people: Iterable[PersonMemoryRecord], query: str
+) -> set[str]:
+    normalized_query = _norm(query)
+    if not normalized_query:
+        return set()
+    return {
+        person.person_id
+        for person in people
+        if any(
+            _query_mentions_explicit_label(normalized_query, _norm(alias))
+            for alias in person.aliases
+        )
+    }
+
+
+def _ambiguous_query_display_name_match_ids(
+    people: Iterable[PersonMemoryRecord], query: str
+) -> set[str]:
+    normalized_query = _norm(query)
+    if not normalized_query:
+        return set()
+    matches_by_name: dict[str, set[str]] = {}
+    for person in people:
+        name = _norm(person.display_name)
+        if not _query_mentions_explicit_label(normalized_query, name):
+            continue
+        matches_by_name.setdefault(name, set()).add(person.person_id)
+    duplicate_matches: set[str] = set()
+    for person_ids in matches_by_name.values():
+        if len(person_ids) > 1:
+            duplicate_matches.update(person_ids)
+    return duplicate_matches
+
+
+def _query_mentions_explicit_label(query: str, label: str) -> bool:
+    if not query or not label:
+        return False
+    if query == label:
+        return True
+    if re.fullmatch(r"[\u4e00-\u9fff]+", label):
+        return len(label) >= 2 and _query_mentions_cjk_alias(query, label)
+    return bool(re.search(rf"\b{re.escape(label)}\b", query, flags=re.IGNORECASE))
+
+
+def _query_mentions_cjk_alias(query: str, label: str) -> bool:
+    for match in re.finditer(re.escape(label), query):
+        left = query[match.start() - 1] if match.start() > 0 else ""
+        right = query[match.end()] if match.end() < len(query) else ""
+        left_ok = (
+            not left
+            or not re.fullmatch(r"[\u4e00-\u9fff]", left)
+            or left in CJK_ALIAS_LEFT_BOUNDARY
+        )
+        right_ok = (
+            not right
+            or not re.fullmatch(r"[\u4e00-\u9fff]", right)
+            or right in CJK_ALIAS_RIGHT_BOUNDARY
+        )
+        if left_ok and right_ok:
+            return True
+    return False
+
+
+def _cjk_name_aliases(label: str) -> list[str]:
+    compact = re.sub(r"\s+", "", label.strip())
+    if compact.startswith("测试"):
+        compact = compact.removeprefix("测试")
+    if not re.fullmatch(r"[\u4e00-\u9fff]{3,4}", compact):
+        return []
+    aliases = [compact, compact[-2:]]
+    return list(dict.fromkeys(alias for alias in aliases if alias and alias != label))
+
+
+def _tokens(text: str) -> set[str]:
+    lowered = text.lower()
+    tokens = {token for token in ASCII_TOKEN_RE.findall(lowered)}
+    for run in CJK_RUN_RE.findall(lowered):
+        chars = [char for char in run if char not in CJK_STOPWORDS]
+        tokens.update(chars)
+        tokens.update(_ngrams(chars, 2))
+        tokens.update(_ngrams(chars, 3))
+    return tokens
+
+
+def _looks_like_follow_up_completion(text: str) -> bool:
+    return bool(
+        re.search(
+            r"(?:已经|已|刚刚|刚)?(?:给|把)[^。；;,.，]{1,40}"
+            r"(?:发了|发送了|发过去了|分享了|转发了)"
+            r"|(?:完成|办完|搞定)[^。；;,.，]{0,40}"
+            r"|\b(?:sent|shared|emailed|completed|finished|done)\b",
+            text,
+            flags=re.IGNORECASE,
+        )
+    )
+
+
+def _completion_matches_follow_up(source_text: str, follow_up: FollowUpTask) -> bool:
+    if follow_up.status != "open":
+        return False
+    source_objects = _send_objects(source_text)
+    follow_up_objects = _send_objects(follow_up.description)
+    if source_objects and follow_up_objects:
+        return any(
+            _similar_task_object(source_object, follow_up_object)
+            for source_object in source_objects
+            for follow_up_object in follow_up_objects
+        )
+    return _task_token_overlap(source_text, follow_up.description) >= 0.58
+
+
+def _mark_matching_follow_ups_done(
+    interactions: Iterable[SocialInteraction], source_text: str
+) -> None:
+    for interaction in interactions:
+        updated: list[FollowUpTask] = []
+        changed = False
+        for follow_up in interaction.follow_ups:
+            if _completion_matches_follow_up(source_text, follow_up):
+                updated.append(follow_up.model_copy(update={"status": "done"}))
+                changed = True
+            else:
+                updated.append(follow_up)
+        if changed:
+            interaction.follow_ups = updated
+
+
+def _send_objects(text: str) -> list[str]:
+    objects: list[str] = []
+    patterns = [
+        r"(?:发|发送)(?:了|过|过去了)?(?:一份|一封|一个|些|一下)?(?P<object>[^，。,.；;]+)",
+        r"(?:sent|shared|emailed)\s+(?P<object>[^.;,]+)",
+    ]
+    for pattern in patterns:
+        for match in re.finditer(pattern, text, flags=re.IGNORECASE):
+            item = _normalize_task_object(match.group("object"))
+            if item:
+                objects.append(item)
+    return list(dict.fromkeys(objects))
+
+
+def _normalize_task_object(text: str) -> str:
+    text = text.casefold().strip()
+    text = re.sub(r"^(?:给|给他|给她|给他们|给她们|给我|to\s+)", "", text).strip()
+    text = re.sub(r"^(?:一份|一封|一个|些|一下|the\s+|a\s+|an\s+)", "", text).strip()
+    return re.sub(r"\s+", " ", text.strip(" \t\r\n,.;:，。！？!?\"'"))
+
+
+def _similar_task_object(left: str, right: str) -> bool:
+    left = _normalize_task_object(left)
+    right = _normalize_task_object(right)
+    if not left or not right:
+        return False
+    if left in right or right in left:
+        return True
+    return _task_token_overlap(left, right) >= 0.72
+
+
+def _task_token_overlap(left: str, right: str) -> float:
+    left_tokens = _task_match_tokens(left)
+    right_tokens = _task_match_tokens(right)
+    if not left_tokens or not right_tokens:
+        return 0.0
+    overlap = left_tokens & right_tokens
+    return len(overlap) / min(len(left_tokens), len(right_tokens))
+
+
+def _task_match_tokens(text: str) -> set[str]:
+    lowered = text.casefold()
+    tokens = {
+        token
+        for token in ASCII_TOKEN_RE.findall(lowered)
+        if len(token) >= 3 and token not in {"the", "and", "for", "with", "sent", "done"}
+    }
+    for run in CJK_RUN_RE.findall(lowered):
+        cleaned = re.sub(
+            r"(今天|昨天|明天|后天|下周[一二三四五六日天]?|上午|下午|晚上|"
+            r"已经|刚刚|一份|一封|一个|给|把|发了|发送了|发过去了|分享了|转发了|完成|搞定)",
+            "",
+            run,
+        )
+        chars = [char for char in cleaned if char not in CJK_STOPWORDS and not char.isdigit()]
+        tokens.update(_ngrams(chars, 2))
+        tokens.update(_ngrams(chars, 3))
+        tokens.update(_ngrams(chars, 4))
+    return tokens
+
+
+def _score(query_tokens: set[str], text: str, person_name: str) -> float:
+    text_tokens = _tokens(text + " " + person_name)
+    if not query_tokens:
+        return 0.0
+    overlap = query_tokens & text_tokens
+    substring_bonus = min(
+        0.6,
+        sum(1 for token in query_tokens if token and token in text.lower()) * 0.15,
+    )
+    return (len(overlap) / max(len(query_tokens), 1)) + substring_bonus
+
+
+def _profile_summary_text(person: PersonMemoryRecord) -> str:
+    parts = [f"Person: {person.display_name}"]
+    if person.aliases:
+        parts.append("Aliases: " + "; ".join(person.aliases))
+    if person.work_history:
+        parts.append(
+            "Works at: "
+            + "; ".join(
+                work.organization
+                + (f" as {work.role}" if work.role else "")
+                for work in person.work_history
+            )
+        )
+    if person.education:
+        parts.append("Studied at: " + "; ".join(edu.school for edu in person.education))
+    if person.interests:
+        parts.append("Interests and discussed topics: " + "; ".join(person.interests))
+    if person.preferences:
+        parts.append("Preferences: " + "; ".join(person.preferences))
+    if len(parts) == 1:
+        return ""
+    return ". ".join(parts) + "."
+
+
+def _relationship_text(relationship: object) -> str:
+    source = getattr(getattr(relationship, "source", None), "label", "Someone")
+    target = getattr(getattr(relationship, "target", None), "label", "someone")
+    relationship_type = str(getattr(relationship, "relationship_type", "associated_with"))
+    return f"{source} {relationship_type.replace('_', ' ')} {target}"
+
+
+def _ngrams(chars: list[str], size: int) -> list[str]:
+    if len(chars) < size:
+        return []
+    return ["".join(chars[index : index + size]) for index in range(len(chars) - size + 1)]
+
+
+def _blocked_by_sensitivity(
+    sensitivity: list[SensitivityLabel], include_sensitive: bool
+) -> bool:
+    if include_sensitive:
+        return False
+    blocked = {
+        SensitivityLabel.SENSITIVE,
+        SensitivityLabel.DO_NOT_SURFACE_UNPROMPTED,
+    }
+    return any(label in blocked for label in sensitivity)
+
+
+def _interaction_sensitivity(interaction: SocialInteraction) -> list[SensitivityLabel]:
+    sensitivity = list(interaction.sensitivity)
+    for claim in interaction.attributed_claims:
+        for label in claim.sensitivity:
+            if label not in sensitivity:
+                sensitivity.append(label)
+    for fact in interaction.direct_facts:
+        for label in fact.sensitivity:
+            if label not in sensitivity:
+                sensitivity.append(label)
+    return sensitivity
+
+
+def _result_evidence(
+    person: PersonMemoryRecord, include_sensitive: bool
+) -> list[Evidence]:
+    if include_sensitive:
+        return person.evidence[-3:]
+    blocked_sources = {
+        interaction.source_text
+        for interaction in person.interactions
+        if _blocked_by_sensitivity(_interaction_sensitivity(interaction), include_sensitive)
+    }
+    safe = [
+        evidence for evidence in person.evidence if evidence.source_text not in blocked_sources
+    ]
+    if safe:
+        return safe[-3:]
+    return person.evidence[-3:]
+
+
+def _extend_unique(target: list, source: list) -> None:
+    existing = {_stable_key(item) for item in target}
+    for item in source:
+        key = _stable_key(item)
+        if key not in existing:
+            target.append(item)
+            existing.add(key)
+
+
+def _append_unique(target: list, item: object) -> None:
+    key = _stable_key(item)
+    if key not in {_stable_key(existing) for existing in target}:
+        target.append(item)
+
+
+def _stable_key(item: object) -> str:
+    if hasattr(item, "model_dump"):
+        return json.dumps(item.model_dump(mode="json"), ensure_ascii=False, sort_keys=True)
+    return json.dumps(item, ensure_ascii=False, sort_keys=True)
+
+
+def _metadata_str(metadata: dict[str, object], key: str) -> str | None:
+    value = metadata.get(key)
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _remap_person_record(record: PersonMemoryRecord, source_person_id: str, target_person_id: str) -> None:
+    for interaction in record.interactions:
+        _remap_interaction(interaction, source_person_id, target_person_id)
+    for fact in record.direct_facts:
+        _remap_ref(fact.subject, source_person_id, target_person_id)
+    for claim in record.attributed_claims:
+        if claim.speaker:
+            _remap_ref(claim.speaker, source_person_id, target_person_id)
+        if claim.subject:
+            _remap_ref(claim.subject, source_person_id, target_person_id)
+    for follow_up in record.follow_ups:
+        for ref in follow_up.related_people:
+            _remap_ref(ref, source_person_id, target_person_id)
+    for relationship in record.relationships:
+        _remap_ref(relationship.source, source_person_id, target_person_id)
+        _remap_ref(relationship.target, source_person_id, target_person_id)
+
+
+def _remap_interaction(
+    interaction: SocialInteraction, source_person_id: str, target_person_id: str
+) -> None:
+    for participant in interaction.participants:
+        _remap_ref(participant.person, source_person_id, target_person_id)
+    for mentioned in interaction.mentioned_people:
+        _remap_ref(mentioned.person, source_person_id, target_person_id)
+        if mentioned.mentioned_by:
+            _remap_ref(mentioned.mentioned_by, source_person_id, target_person_id)
+    for claim in interaction.attributed_claims:
+        if claim.speaker:
+            _remap_ref(claim.speaker, source_person_id, target_person_id)
+        if claim.subject:
+            _remap_ref(claim.subject, source_person_id, target_person_id)
+    for fact in interaction.direct_facts:
+        _remap_ref(fact.subject, source_person_id, target_person_id)
+    for follow_up in interaction.follow_ups:
+        for ref in follow_up.related_people:
+            _remap_ref(ref, source_person_id, target_person_id)
+    for relationship in interaction.relationships:
+        _remap_ref(relationship.source, source_person_id, target_person_id)
+        _remap_ref(relationship.target, source_person_id, target_person_id)
+
+
+def _remap_ref(ref: PersonRef, source_person_id: str, target_person_id: str) -> None:
+    if ref.person_id == source_person_id:
+        ref.person_id = target_person_id