pdm-memory 0.1.8__tar.gz → 0.2.0__tar.gz

{pdm_memory-0.1.8 → pdm_memory-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdm-memory
-Version: 0.1.8
+Version: 0.2.0
 Summary: Pressure-Driven Memory (PDM) — persistent, resonance-based memory for AI apps.
 Author: Westfield Innovations LLC
 License: Elastic License 2.0 (ELv2)
@@ -115,8 +115,8 @@ License: Elastic License 2.0 (ELv2)
         **trademark** means trademarks, service marks, and similar rights.
         
 Project-URL: Homepage, https://azus.ai
-Project-URL: Documentation, https://azus.ai
-Project-URL: Bug Tracker, https://github.com/westfield-innovations/pdm-memory/issues
+Project-URL: Documentation, https://azus.ai/support
+Project-URL: Bug Tracker, https://azus.ai/support?tab=bugs
 Project-URL: Source, https://github.com/westfield-innovations/pdm-memory
 Project-URL: Repository, https://github.com/westfield-innovations/pdm-memory
 Keywords: ai,memory,llm,rag,pressure-driven,persistent-memory
@@ -154,6 +154,8 @@ Requires-Dist: groq>=0.9.0; extra == "all"
 Provides-Extra: ui
 Requires-Dist: fastapi>=0.110; extra == "ui"
 Requires-Dist: uvicorn[standard]>=0.27; extra == "ui"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -175,6 +177,7 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/pdm-memory)](https://pypi.org/project/pdm-memory/)
 [![CI](https://github.com/westfield-innovations/pdm-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/westfield-innovations/pdm-memory/actions)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary%20ELv2-blue)](LICENSE)
+[![Documentation](https://img.shields.io/badge/Docs-azus.ai%2Fsupport-blue)](https://azus.ai/support)
 
 Your LLM forgets everything between conversations. The standard fix — stuff a vector database into the context window — is expensive, slow, and retrieves **what matches words, not what matters**.
 
@@ -184,12 +187,15 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
 - 🗄️ **Your storage.** One local file. Your data never leaves your machine. Check the source — there's no phone-home in it.
 - ⚡ **Ten minutes.** `pip install pdm-memory` → three lines → persistent memory.
 
+📖 **Documentation:** [azus.ai/support](https://azus.ai/support)
+
 **Benchmarks vs standard RAG:** [link] · Run yourself: `python -m pdm_memory.bench`
 
 ---
 
 ## Table of Contents
 
+0. [Documentation](https://azus.ai/support)
 1. [Privacy Mode](#-privacy-mode-local-sqlite)
 2. [Ecosystem Mode](#-ecosystem-mode-azus-cloud)
 3. [LLM Adapters](#-llm-adapters)

{pdm_memory-0.1.8 → pdm_memory-0.2.0}/README.md

@@ -4,6 +4,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/pdm-memory)](https://pypi.org/project/pdm-memory/)
 [![CI](https://github.com/westfield-innovations/pdm-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/westfield-innovations/pdm-memory/actions)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary%20ELv2-blue)](LICENSE)
+[![Documentation](https://img.shields.io/badge/Docs-azus.ai%2Fsupport-blue)](https://azus.ai/support)
 
 Your LLM forgets everything between conversations. The standard fix — stuff a vector database into the context window — is expensive, slow, and retrieves **what matches words, not what matters**.
 
@@ -13,12 +14,15 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
 - 🗄️ **Your storage.** One local file. Your data never leaves your machine. Check the source — there's no phone-home in it.
 - ⚡ **Ten minutes.** `pip install pdm-memory` → three lines → persistent memory.
 
+📖 **Documentation:** [azus.ai/support](https://azus.ai/support)
+
 **Benchmarks vs standard RAG:** [link] · Run yourself: `python -m pdm_memory.bench`
 
 ---
 
 ## Table of Contents
 
+0. [Documentation](https://azus.ai/support)
 1. [Privacy Mode](#-privacy-mode-local-sqlite)
 2. [Ecosystem Mode](#-ecosystem-mode-azus-cloud)
 3. [LLM Adapters](#-llm-adapters)

{pdm_memory-0.1.8 → pdm_memory-0.2.0}/pdm_memory/__init__.py

@@ -21,7 +21,18 @@ See README.md for full documentation.
 
 from pdm_memory.memory import Memory
 from pdm_memory.core.signature import MemoryHit, DrawerInfo
-from pdm_memory.models import AlignmentReport, TorsionReport
-
-__version__ = "0.1.8"
-__all__ = ["Memory", "MemoryHit", "DrawerInfo", "AlignmentReport", "TorsionReport", "__version__"]
+from pdm_memory.models import AlignmentReport, SurfaceReport, TorsionReport
+from pdm_memory.storage.factory import create_storage, register_storage
+
+__version__ = "0.2.0"
+__all__ = [
+    "Memory",
+    "MemoryHit",
+    "DrawerInfo",
+    "AlignmentReport",
+    "SurfaceReport",
+    "TorsionReport",
+    "create_storage",
+    "register_storage",
+    "__version__",
+]

{pdm_memory-0.1.8 → pdm_memory-0.2.0}/pdm_memory/core/retrieval.py

@@ -21,7 +21,10 @@ import math
 import logging
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pdm_memory.types import TorsionJudge
 
 from pdm_memory.core.math import (
     P_MAX,
@@ -47,10 +50,47 @@ _TOPIC_GATE: float = 0.35
 _SMALL_CLUSTER: int = 48
 _NEGATION_TOKENS: frozenset[str] = frozenset(
     {
-        "not", "never", "no", "false", "isn't", "aren't", "wasn't", "weren't",
-        "cannot", "can't", "won't", "without", "none", "neither",
+        # English (incl. typo / no-apostrophe forms users actually type)
+        "not",
+        "never",
+        "no",
+        "false",
+        "without",
+        "none",
+        "neither",
+        "nor",
+        "cannot",
+        "dont",
+        "doesnt",
+        "didnt",
+        "isnt",
+        "arent",
+        "wasnt",
+        "werent",
+        "wont",
+        "cant",
+        "shouldnt",
+        "wouldnt",
+        "couldnt",
     }
 )
+# Applied before polarity checks — user text is messy
+_CONTRACTION_MAP: Tuple[Tuple[str, str], ...] = (
+    ("don't", " do not "),
+    ("doesn't", " does not "),
+    ("didn't", " did not "),
+    ("isn't", " is not "),
+    ("aren't", " are not "),
+    ("wasn't", " was not "),
+    ("weren't", " were not "),
+    ("won't", " will not "),
+    ("can't", " can not "),
+    ("shouldn't", " should not "),
+    ("wouldn't", " would not "),
+    ("couldn't", " could not "),
+    ("cannot", " can not "),
+    ("n't", " not "),
+)
 _ANTONYM_PAIRS: Tuple[Tuple[str, str], ...] = (
     ("prefer", "avoid"),
     ("likes", "hates"),
@@ -241,6 +281,9 @@ class RetrievalEngine:
             )
 
             if coupling.is_coupled:
+                if query_tags and self._semantic_query_overlap(rec, query_tags) < 0.12:
+                    damped.append(coupling)
+                    continue
                 hit = MemoryHit.from_record(
                     rec, p_eff, decay, i_weight, v,
                     coupling_score=coupling.coupling_score,
@@ -258,6 +301,37 @@ class RetrievalEngine:
 
         return [hit for _, hit in coupled[:k]]
 
+    @staticmethod
+    def _semantic_query_overlap(rec: SignatureRecord, query_tags: Sequence[str]) -> float:
+        """
+        Tag or fact-token overlap between query and signature.
+
+        Blocks high-P memories from coupling when tags do not match and the
+        fact text shares no meaningful tokens with the query.
+        """
+        if not query_tags:
+            return 1.0
+        cue = {t.lower() for t in query_tags if t}
+        sig_tags = {t.lower() for t in (rec.intent_tags or []) if t}
+        if RetrievalEngine._tags_overlap(cue, sig_tags):
+            return 1.0
+        fact_tokens = set(RetrievalEngine._tokenize_query(rec.compressed_fact or ""))
+        if not fact_tokens:
+            return 0.0
+        if RetrievalEngine._tags_overlap(cue, fact_tokens):
+            return 1.0
+        return len(fact_tokens & cue) / max(len(fact_tokens | cue), 1)
+
+    @staticmethod
+    def _tags_overlap(cue: Set[str], tags: Set[str]) -> bool:
+        if cue & tags:
+            return True
+        for q in cue:
+            for t in tags:
+                if len(q) >= 4 and (q in t or t in q):
+                    return True
+        return False
+
     def compute_reinforcement_delta(
         self,
         p_magnitude: float,
@@ -371,6 +445,7 @@ class RetrievalEngine:
         self,
         records: Sequence[SignatureRecord],
         threshold: float = 0.7,
+        judge: Optional["TorsionJudge"] = None,
     ) -> List[TorsionReport]:
         """
         Find Reverse Resonance pairs: high topic similarity + opposing facts/pressure.
@@ -378,6 +453,8 @@ class RetrievalEngine:
         Search space is limited to drawer/domain (or metadata ``cluster_id``) buckets.
         Within a bucket, candidates come from a tag inverted index (shared intent tags).
         Small buckets may also compare all pairs. Never runs blind global N².
+
+        Optional ``judge`` callback may flag pairs rules-only detection missed (e.g. paraphrase).
         """
         if threshold < 0.0 or threshold > 1.0:
             raise ValueError("threshold must be in [0.0, 1.0]")
@@ -392,6 +469,7 @@ class RetrievalEngine:
 
         reports: List[TorsionReport] = []
         seen_pairs: Set[Tuple[str, str]] = set()
+        reported_pairs: Set[Tuple[str, str]] = set()
 
         for cluster_key, group in clusters.items():
             if len(group) < 2:
@@ -405,10 +483,47 @@ class RetrievalEngine:
                 report = self._score_torsion_pair(a, b, cluster_key=cluster_key)
                 if report is not None and report.torsion_score >= threshold:
                     reports.append(report)
+                    reported_pairs.add(pair_key)
+
+        if judge is not None:
+            reports = self._merge_judge_reports(
+                clusters, reports, threshold, judge, reported_pairs
+            )
 
         reports.sort(key=lambda r: r.torsion_score, reverse=True)
         return reports
 
+    def _merge_judge_reports(
+        self,
+        clusters: Dict[str, List[SignatureRecord]],
+        reports: List[TorsionReport],
+        threshold: float,
+        judge: "TorsionJudge",
+        reported_pairs: Set[Tuple[str, str]],
+    ) -> List[TorsionReport]:
+        """Append judge-flagged pairs not already reported by rules-only detection."""
+        merged = list(reports)
+        seen_pairs: Set[Tuple[str, str]] = set()
+        for group in clusters.values():
+            if len(group) < 2:
+                continue
+            for a, b in self._torsion_candidate_pairs(group):
+                pair_key = (a.id, b.id) if a.id < b.id else (b.id, a.id)
+                if pair_key in seen_pairs or pair_key in reported_pairs:
+                    continue
+                seen_pairs.add(pair_key)
+                try:
+                    judged = judge(a, b)
+                except Exception as exc:
+                    logger.warning("[PDM] torsion_judge failed for pair: %s", exc)
+                    continue
+                if judged is None or judged.torsion_score < threshold:
+                    continue
+                reported_pairs.add(pair_key)
+                merged.append(judged)
+        merged.sort(key=lambda r: r.torsion_score, reverse=True)
+        return merged
+
     def _torsion_candidate_pairs(
         self,
         group: Sequence[SignatureRecord],
@@ -550,8 +665,10 @@ class RetrievalEngine:
                 best_kind, best_strength, best_detail = "factual", strength, detail
 
         # Negation / antonym polarity on shared content
-        tok_a = set(self._tokenize_query(a.compressed_fact or ""))
-        tok_b = set(self._tokenize_query(b.compressed_fact or ""))
+        norm_a = self._normalize_polarity_text(a.compressed_fact or "")
+        norm_b = self._normalize_polarity_text(b.compressed_fact or "")
+        tok_a = set(self._tokenize_query(norm_a))
+        tok_b = set(self._tokenize_query(norm_b))
         content_a = tok_a - _NEGATION_TOKENS
         content_b = tok_b - _NEGATION_TOKENS
         content_overlap = (
@@ -559,8 +676,8 @@ class RetrievalEngine:
             if content_a or content_b
             else 0.0
         )
-        neg_a = bool(_NEGATION_TOKENS & set(WORD_PATTERN.findall((a.compressed_fact or "").lower())))
-        neg_b = bool(_NEGATION_TOKENS & set(WORD_PATTERN.findall((b.compressed_fact or "").lower())))
+        neg_a = self._has_negation(norm_a)
+        neg_b = self._has_negation(norm_b)
         if neg_a != neg_b and content_overlap >= 0.28:
             strength = min(1.0, 0.45 + 0.55 * content_overlap)
             if strength > best_strength:
@@ -570,8 +687,8 @@ class RetrievalEngine:
                     "one affirms, the other negates the shared topic",
                 )
 
-        text_blob_a = f"{' '.join(a.intent_tags or [])} {(a.compressed_fact or '')}".lower()
-        text_blob_b = f"{' '.join(b.intent_tags or [])} {(b.compressed_fact or '')}".lower()
+        text_blob_a = f"{' '.join(a.intent_tags or [])} {norm_a}".lower()
+        text_blob_b = f"{' '.join(b.intent_tags or [])} {norm_b}".lower()
         for left, right in _ANTONYM_PAIRS:
             a_has_l, a_has_r = left in text_blob_a, right in text_blob_a
             b_has_l, b_has_r = left in text_blob_b, right in text_blob_b
@@ -635,6 +752,38 @@ class RetrievalEngine:
             case _:
                 return f"{base}: reverse resonance on a shared topic."
 
+    @staticmethod
+    def _normalize_polarity_text(text: str) -> str:
+        """Expand contractions / slang so negation tokens become detectable."""
+        t = (text or "").lower()
+        for src, dst in _CONTRACTION_MAP:
+            t = t.replace(src, dst)
+        # Common no-apostrophe typos after apostrophe expansion
+        for src, dst in (
+            (" dont ", " do not "),
+            (" doesnt ", " does not "),
+            (" didnt ", " did not "),
+            (" isnt ", " is not "),
+            (" arent ", " are not "),
+            (" wasnt ", " was not "),
+            (" werent ", " were not "),
+            (" wont ", " will not "),
+            (" cant ", " can not "),
+        ):
+            t = t.replace(src, dst)
+        # Leading typo without spaces: "i dont love" already spaced by lower()
+        if t.startswith("dont "):
+            t = "do not " + t[5:]
+        return t
+
+    @staticmethod
+    def _has_negation(text: str) -> bool:
+        """True if text contains an English negation cue after normalization."""
+        norm = RetrievalEngine._normalize_polarity_text(text)
+        tokens = set(WORD_PATTERN.findall(norm))
+        # Also catch leftover no-apostrophe forms as whole tokens
+        return bool(tokens & _NEGATION_TOKENS)
+
     @staticmethod
     def _standalone_numbers(text: str) -> set[str]:
         """Extract numeric tokens that are not glued to letters (skip Q3, v2)."""

{pdm_memory-0.1.8 → pdm_memory-0.2.0}/pdm_memory/core/signature.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import uuid
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 
@@ -69,9 +69,13 @@ class SignatureRecord:
     # Extra metadata
     metadata: Dict[str, Any] = field(default_factory=dict)
 
+    # Storage / lifecycle (Tier 3)
+    is_deleted: bool = False
+    idempotency_key: Optional[str] = None
+
     def __post_init__(self) -> None:
         if self.created_at is None:
-            self.created_at = datetime.utcnow()
+            self.created_at = datetime.now(tz=timezone.utc)
         if self.effective_spike is None:
             from pdm_memory.core.math import calculate_effective_spike
             self.effective_spike = calculate_effective_spike(

pdm_memory-0.2.0/pdm_memory/io/__init__.py

@@ -0,0 +1,6 @@
+# © 2026 Westfield Innovations LLC. Patent Pending.
+"""PDM import/export helpers."""
+
+from pdm_memory.io.json_transfer import export_signatures_json, import_signatures_json
+
+__all__ = ["export_signatures_json", "import_signatures_json"]

pdm_memory-0.2.0/pdm_memory/io/json_transfer.py

@@ -0,0 +1,189 @@
+# © 2026 Westfield Innovations LLC. Patent Pending.
+# U.S. App. No. 19/739,419 | 63/953,563 | 63/953,842
+# MODIFICATION PROHIBITED. USE AS SHIPPED.
+
+"""JSON export/import for PDM signatures — backup and cross-backend migration."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, List, Union
+
+from pdm_memory.core.signature import SignatureRecord
+from pdm_memory.storage.base import BaseStorage
+from pdm_memory.storage.schema import hash_fact_text
+
+_EXPORT_VERSION = "1"
+
+
+def _dt_to_iso(value: datetime | None) -> str | None:
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.isoformat()
+
+
+def _iso_to_dt(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value)
+    except (TypeError, ValueError):
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def record_to_dict(rec: SignatureRecord) -> dict[str, Any]:
+    """Serialize a SignatureRecord to a JSON-safe dict."""
+    return {
+        "id": rec.id,
+        "user": rec.user,
+        "compressed_fact": rec.compressed_fact,
+        "source": rec.source,
+        "p_magnitude": rec.p_magnitude,
+        "t_persistence": rec.t_persistence,
+        "phase_privilege": rec.phase_privilege,
+        "effective_spike": rec.effective_spike,
+        "intent_tags": list(rec.intent_tags or []),
+        "question_regime": rec.question_regime,
+        "domain": rec.domain,
+        "drawer_domain": rec.drawer_domain,
+        "retrieval_count": rec.retrieval_count,
+        "last_retrieved": _dt_to_iso(rec.last_retrieved),
+        "created_at": _dt_to_iso(rec.created_at),
+        "validation_prediction_total": rec.validation_prediction_total,
+        "validation_prediction_correct": rec.validation_prediction_correct,
+        "decay_rate": rec.decay_rate,
+        "t_deadline": _dt_to_iso(rec.t_deadline),
+        "urgency_rate": rec.urgency_rate,
+        "metadata": dict(rec.metadata or {}),
+    }
+
+
+def dict_to_record(data: dict[str, Any], *, user: str) -> SignatureRecord:
+    """Deserialize a JSON dict into SignatureRecord."""
+    text = str(data.get("compressed_fact") or data.get("text") or "").strip()
+    tags = data.get("intent_tags") or data.get("tags") or []
+    if isinstance(tags, str):
+        tags = [t.strip() for t in tags.split(",") if t.strip()]
+
+    return SignatureRecord(
+        id=str(data.get("id") or ""),
+        user=user,
+        compressed_fact=text,
+        source=str(data.get("source") or "import"),
+        p_magnitude=float(data.get("p_magnitude", 50.0)),
+        t_persistence=float(data.get("t_persistence", 30.0)),
+        phase_privilege=float(data.get("phase_privilege", 1.0)),
+        effective_spike=data.get("effective_spike"),
+        intent_tags=list(tags),
+        question_regime=str(data.get("question_regime") or "neutral"),
+        domain=str(data.get("domain") or "insight"),
+        drawer_domain=str(data.get("drawer_domain") or data.get("drawer") or "general"),
+        retrieval_count=int(data.get("retrieval_count") or 0),
+        last_retrieved=_iso_to_dt(data.get("last_retrieved")),
+        created_at=_iso_to_dt(data.get("created_at")),
+        validation_prediction_total=int(data.get("validation_prediction_total") or 0),
+        validation_prediction_correct=int(data.get("validation_prediction_correct") or 0),
+        decay_rate=float(data.get("decay_rate", 0.9)),
+        t_deadline=_iso_to_dt(data.get("t_deadline")),
+        urgency_rate=float(data.get("urgency_rate", 2.0)),
+        metadata=dict(data.get("metadata") or {}),
+    )
+
+
+def export_signatures_json(
+    storage: BaseStorage,
+    path: Union[str, Path],
+    *,
+    user: str = "default",
+    limit: int = 100_000,
+) -> int:
+    """
+    Export all signatures for ``user`` to a JSON file.
+
+    Returns:
+        Number of signatures written.
+    """
+    records = storage.list(user=user, limit=limit)
+    payload = {
+        "version": _EXPORT_VERSION,
+        "exported_at": datetime.now(tz=timezone.utc).isoformat(),
+        "user": user,
+        "count": len(records),
+        "signatures": [record_to_dict(r) for r in records],
+    }
+    out = Path(path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    return len(records)
+
+
+def import_signatures_json(
+    storage: BaseStorage,
+    path: Union[str, Path],
+    *,
+    user: str = "default",
+    skip_duplicates: bool = True,
+) -> dict[str, int]:
+    """
+    Import signatures from a JSON export file.
+
+    When ``skip_duplicates`` is True, skips rows whose id or fact hash already exist.
+    """
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    items: List[dict[str, Any]] = raw.get("signatures") or raw.get("records") or []
+    if not isinstance(items, list):
+        raise ValueError("JSON must contain a 'signatures' array")
+
+    saved = 0
+    skipped = 0
+    errors = 0
+
+    txn = getattr(storage, "transaction", None)
+    if callable(txn):
+        ctx = txn()
+    else:
+        from contextlib import nullcontext
+
+        ctx = nullcontext()
+
+    with ctx:
+        for item in items:
+            if not isinstance(item, dict):
+                errors += 1
+                continue
+            try:
+                rec = dict_to_record(item, user=user)
+                if not rec.compressed_fact:
+                    errors += 1
+                    continue
+                if not rec.id:
+                    import uuid
+
+                    rec.id = str(uuid.uuid4())
+
+                if skip_duplicates:
+                    if storage.get(rec.id, user=user) is not None:
+                        skipped += 1
+                        continue
+                    fact = rec.compressed_fact
+                    if fact.startswith("[HASH:") and fact.endswith("]"):
+                        text_hash = fact[6:-1]
+                    else:
+                        text_hash = hash_fact_text(fact.strip()[:500])
+                    if storage.find_by_hash(text_hash, user=user) is not None:
+                        skipped += 1
+                        continue
+
+                storage.save(rec)
+                saved += 1
+            except Exception:
+                errors += 1
+
+    return {"saved": saved, "skipped": skipped, "errors": errors}