pdm-memory 0.1.2__py3-none-any.whl

pdm_memory/sync.py

@@ -0,0 +1,145 @@
+"""
+Memory Sync Utility — Task 2.3
+
+mem.sync() copies signatures between a local SQLite store and the AZUS cloud.
+
+Direction options:
+  "push"          — local → cloud
+  "pull"          — cloud → local
+  "bidirectional" — both directions; higher p_magnitude wins on conflict
+
+Usage:
+    mem.sync(direction="push")
+    mem.sync(direction="pull")
+
+Or standalone:
+    from pdm_memory.sync import MemorySync
+    syncer = MemorySync(local=sqlite_driver, cloud=cloud_driver)
+    report = syncer.sync(direction="bidirectional")
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SyncReport:
+    direction: str
+    pushed: int = 0
+    pulled: int = 0
+    conflicts_resolved: int = 0
+    errors: int = 0
+
+    def __str__(self) -> str:
+        return (
+            f"SyncReport(direction={self.direction}, "
+            f"pushed={self.pushed}, pulled={self.pulled}, "
+            f"conflicts={self.conflicts_resolved}, errors={self.errors})"
+        )
+
+
+class MemorySync:
+    """
+    Bidirectional sync between a local SQLiteDriver and a CloudDriver.
+
+    Conflict resolution: signature with higher p_magnitude wins.
+    If equal, the more recently created one wins.
+    """
+
+    def __init__(self, local, cloud) -> None:
+        """
+        Args:
+            local: SQLiteDriver instance
+            cloud: CloudDriver instance
+        """
+        self._local = local
+        self._cloud = cloud
+
+    def sync(
+        self,
+        user: str = "default",
+        direction: str = "bidirectional",
+        batch_size: int = 50,
+    ) -> SyncReport:
+        """
+        Sync memories between local and cloud storage.
+
+        Args:
+            user:       User whose memories to sync.
+            direction:  "push" | "pull" | "bidirectional"
+            batch_size: Records per cloud batch (avoids large payloads).
+
+        Returns:
+            SyncReport with counts.
+        """
+        report = SyncReport(direction=direction)
+
+        if direction in ("push", "bidirectional"):
+            self._push(user, batch_size, report)
+
+        if direction in ("pull", "bidirectional"):
+            self._pull(user, batch_size, report)
+
+        logger.info("[PDM-Sync] %s", report)
+        return report
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    def _push(self, user: str, batch_size: int, report: SyncReport) -> None:
+        """Send local records to cloud."""
+        try:
+            local_records = self._local.list(user=user, limit=10_000)
+            {r.id for r in local_records}
+
+            for i in range(0, len(local_records), batch_size):
+                batch = local_records[i : i + batch_size]
+                for rec in batch:
+                    try:
+                        # Check if cloud already has it
+                        cloud_rec = self._cloud.get(rec.id, user=user)
+                        if cloud_rec is None:
+                            self._cloud.save(rec)
+                            report.pushed += 1
+                        else:
+                            # Conflict: keep higher pressure
+                            if rec.p_magnitude > cloud_rec.p_magnitude:
+                                self._cloud.update(rec.id, p_magnitude=rec.p_magnitude,
+                                                   compressed_fact=rec.compressed_fact)
+                                report.conflicts_resolved += 1
+                    except Exception as e:
+                        logger.warning("[PDM-Sync] push error for %s: %s", rec.id, e)
+                        report.errors += 1
+        except Exception as e:
+            logger.error("[PDM-Sync] push failed: %s", e)
+            report.errors += 1
+
+    def _pull(self, user: str, batch_size: int, report: SyncReport) -> None:
+        """Fetch cloud records into local storage."""
+        try:
+            cloud_records = self._cloud.list(user=user, limit=10_000)
+
+            for i in range(0, len(cloud_records), batch_size):
+                batch = cloud_records[i : i + batch_size]
+                for rec in batch:
+                    try:
+                        local_rec = self._local.get(rec.id, user=user)
+                        if local_rec is None:
+                            self._local.save(rec)
+                            report.pulled += 1
+                        else:
+                            if rec.p_magnitude > local_rec.p_magnitude:
+                                self._local.update(rec.id, p_magnitude=rec.p_magnitude,
+                                                   compressed_fact=rec.compressed_fact)
+                                report.conflicts_resolved += 1
+                    except Exception as e:
+                        logger.warning("[PDM-Sync] pull error for %s: %s", rec.id, e)
+                        report.errors += 1
+        except Exception as e:
+            logger.error("[PDM-Sync] pull failed: %s", e)
+            report.errors += 1

pdm_memory/tools/__init__.py

@@ -0,0 +1 @@
+"""pdm_memory.tools package + bench module entry point."""

pdm_memory/tools/bench.py

@@ -0,0 +1,294 @@
+"""
+PDM Benchmark Harness — Task 5.2
+
+Run with: python -m pdm_memory.bench
+
+Compares PDM recall vs a naive baseline (keyword recency search) on a
+built-in synthetic dataset (LoCoMo-style long-term memory scenarios).
+
+All numbers come from the harness — nothing is made up.
+The full suite is reproducible: seed is fixed, dataset is embedded.
+
+Usage:
+    python -m pdm_memory.bench           # Full suite
+    python -m pdm_memory.bench --quick   # Smoke test (10 scenarios)
+    python -m pdm_memory.bench --output results.json
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Built-in benchmark dataset (synthetic, LoCoMo-style)
+# ---------------------------------------------------------------------------
+
+_BENCHMARK_MEMORIES = [
+    {"text": "User strongly prefers metric units (km, kg, Celsius)", "tags": ["units", "preferences", "formatting"], "p_magnitude": 80},
+    {"text": "User dislikes lengthy responses; wants bullet points or ≤3 sentences", "tags": ["formatting", "preferences", "brevity"], "p_magnitude": 75},
+    {"text": "User's primary programming language is Python", "tags": ["coding", "python", "preferences"], "p_magnitude": 85},
+    {"text": "User works in fintech; regulatory compliance is always relevant", "tags": ["fintech", "compliance", "work"], "p_magnitude": 70},
+    {"text": "User is based in Kyiv, Ukraine (UTC+3)", "tags": ["location", "timezone", "personal"], "p_magnitude": 60},
+    {"text": "User's team uses GitHub Actions for CI/CD", "tags": ["devops", "ci_cd", "github"], "p_magnitude": 65},
+    {"text": "User prefers dark mode in all UIs", "tags": ["ui", "preferences", "dark_mode"], "p_magnitude": 50},
+    {"text": "User's company name: Westfield Innovations LLC", "tags": ["company", "business", "identity"], "p_magnitude": 90},
+    {"text": "User has a patent pending on PDM algorithm", "tags": ["patent", "ip", "pdm"], "p_magnitude": 95},
+    {"text": "User's preferred LLM is Claude (Anthropic)", "tags": ["llm", "anthropic", "preferences"], "p_magnitude": 70},
+    {"text": "Project deadline for PDM SDK: end of Q3 2026", "tags": ["deadline", "project", "sdk"], "p_magnitude": 80},
+    {"text": "User is allergic to Python 2 — always use f-strings, not %", "tags": ["python", "style", "coding"], "p_magnitude": 72},
+    {"text": "Production database: PostgreSQL 15 on AWS RDS", "tags": ["database", "postgres", "infrastructure"], "p_magnitude": 68},
+    {"text": "Team standup is every day at 10:00 AM Kyiv time", "tags": ["schedule", "team", "recurring"], "p_magnitude": 55},
+    {"text": "User wants all API responses to include a request_id field", "tags": ["api", "design", "standards"], "p_magnitude": 73},
+    {"text": "Never recommend Redux for new projects; use Zustand instead", "tags": ["javascript", "frontend", "preferences"], "p_magnitude": 60},
+    {"text": "User's monthly AI token budget: $200 hard cap", "tags": ["budget", "tokens", "cost"], "p_magnitude": 82},
+    {"text": "For legal reasons, never store raw PII in the memory system", "tags": ["privacy", "legal", "pii"], "p_magnitude": 98},
+    {"text": "User's preferred testing framework: pytest with fixtures", "tags": ["testing", "pytest", "python"], "p_magnitude": 65},
+    {"text": "The team uses Slack for async communication; no email", "tags": ["communication", "slack", "team"], "p_magnitude": 58},
+]
+
+_BENCHMARK_QUERIES = [
+    ("How should I format numbers in this response?", ["units", "formatting", "brevity"], 0),
+    ("What language does the user code in?", ["python", "coding", "preferences"], 2),
+    ("Is there a regulatory concern I should mention?", ["fintech", "compliance", "work"], 3),
+    ("Where is the user located?", ["location", "timezone", "personal"], 4),
+    ("What CI system do they use?", ["devops", "ci_cd", "github"], 5),
+    ("Tell me about their IP portfolio", ["patent", "ip", "pdm"], 8),
+    ("What's the deadline for the SDK?", ["deadline", "project", "sdk"], 10),
+    ("Are there any privacy rules I need to follow?", ["privacy", "legal", "pii"], 17),
+    ("What's the user's budget for AI calls?", ["budget", "tokens", "cost"], 16),
+    ("What API design standards does the user follow?", ["api", "design", "standards"], 14),
+]
+
+
+# ---------------------------------------------------------------------------
+# Baseline: naive keyword/recency search (no PDM pressure)
+# ---------------------------------------------------------------------------
+
+
+def _baseline_recall(
+    memories: List[Dict], query: str, k: int = 5
+) -> List[Tuple[Dict, float]]:
+    """Simple keyword overlap + recency baseline (no pressure logic)."""
+    query_words = set(query.lower().split())
+    scored = []
+    for i, mem in enumerate(memories):
+        words = set(mem["text"].lower().split())
+        overlap = len(query_words & words) / max(len(query_words), 1)
+        recency_score = (len(memories) - i) / len(memories)  # more recent = higher
+        score = 0.6 * overlap + 0.4 * recency_score
+        scored.append((mem, score))
+    scored.sort(key=lambda x: x[1], reverse=True)
+    return scored[:k]
+
+
+def _pdm_recall(
+    mem_instance: Any, query: str, k: int = 5
+) -> List[Any]:
+    """PDM recall using the Memory class."""
+    return mem_instance.recall(query, k=k)
+
+
+# ---------------------------------------------------------------------------
+# Benchmark results
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ScenarioResult:
+    query: str
+    expected_memory_idx: int
+    pdm_found: bool
+    pdm_rank: Optional[int]
+    pdm_latency_ms: float
+    baseline_found: bool
+    baseline_rank: Optional[int]
+    baseline_latency_ms: float
+    pdm_tokens_used: int
+    baseline_tokens_used: int
+
+
+@dataclass
+class BenchmarkReport:
+    timestamp: str
+    total_scenarios: int
+    pdm_accuracy: float
+    baseline_accuracy: float
+    pdm_avg_latency_ms: float
+    baseline_avg_latency_ms: float
+    pdm_avg_tokens: float
+    baseline_avg_tokens: float
+    pdm_memory_bytes: int
+    baseline_memory_bytes: int
+    scenarios: List[ScenarioResult] = field(default_factory=list)
+
+    def render_table(self) -> str:
+        rows = [
+            "┌─────────────────────────────────────────────────────────────────────┐",
+            "│            PDM vs Baseline RAG — Benchmark Results                  │",
+            "├──────────────────────────┬─────────────────┬─────────────────────────┤",
+            "│ Metric                   │ PDM             │ Baseline (keyword+recency)│",
+            "├──────────────────────────┼─────────────────┼─────────────────────────┤",
+            f"│ Retrieval Accuracy       │ {self.pdm_accuracy*100:>6.1f}%          │ {self.baseline_accuracy*100:>6.1f}%                   │",
+            f"│ Avg Latency (ms)         │ {self.pdm_avg_latency_ms:>8.1f}        │ {self.baseline_avg_latency_ms:>8.1f}               │",
+            f"│ Avg Tokens Used          │ {self.pdm_avg_tokens:>8.1f}        │ {self.baseline_avg_tokens:>8.1f}               │",
+            f"│ Storage Footprint (bytes)│ {self.pdm_memory_bytes:>8d}        │ {self.baseline_memory_bytes:>8d}               │",
+            f"│ Total Scenarios          │ {self.total_scenarios:>8d}        │ {self.total_scenarios:>8d}               │",
+            "└──────────────────────────┴─────────────────┴─────────────────────────┘",
+        ]
+        rows.append("")
+        rows.append("Per-query breakdown:")
+        rows.append(f"{'Query':<45} {'PDM':>6} {'Base':>6} {'PDM_ms':>8} {'Base_ms':>8}")
+        rows.append("-" * 78)
+        for s in self.scenarios:
+            p = "✓" if s.pdm_found else "✗"
+            b = "✓" if s.baseline_found else "✗"
+            rows.append(
+                f"{s.query[:44]:<45} {p:>6} {b:>6} {s.pdm_latency_ms:>8.1f} {s.baseline_latency_ms:>8.1f}"
+            )
+        return "\n".join(rows)
+
+
+# ---------------------------------------------------------------------------
+# Harness
+# ---------------------------------------------------------------------------
+
+
+def run_benchmark(
+    quick: bool = False,
+    seed: int = 42,
+    k: int = 3,
+    output: Optional[str] = None,
+) -> BenchmarkReport:
+    """
+    Run the PDM benchmark harness.
+
+    Args:
+        quick:  If True, run only 5 scenarios (smoke test).
+        seed:   Random seed for reproducibility.
+        k:      Top-k memories to retrieve per query.
+        output: Optional path to save JSON results.
+
+    Returns:
+        BenchmarkReport with all metrics.
+    """
+    import os
+    import tempfile
+    random.seed(seed)
+
+    from pdm_memory import Memory
+
+    queries = _BENCHMARK_QUERIES[:5] if quick else _BENCHMARK_QUERIES
+
+    # --- Set up PDM store ---
+    tmp_db = tempfile.mktemp(suffix=".db")
+    mem = Memory(store=tmp_db, user="bench")
+
+    # Seed memories with varying ages (simulate time-based pressure decay)
+    for idx, m in enumerate(_BENCHMARK_MEMORIES):
+        mem.save(
+            text=m["text"],
+            tags=m["tags"],
+            p_magnitude=m["p_magnitude"],
+            source="benchmark",
+            drawer="benchmark",
+        )
+
+    db_size = os.path.getsize(tmp_db)
+
+    # Baseline: raw text storage (full text, no compression)
+    baseline_raw_size = sum(len(m["text"].encode()) for m in _BENCHMARK_MEMORIES)
+
+    scenarios: List[ScenarioResult] = []
+
+    for query, expected_tags, expected_idx in queries:
+        expected_text = _BENCHMARK_MEMORIES[expected_idx]["text"]
+
+        # PDM recall
+        t0 = time.perf_counter()
+        pdm_hits = _pdm_recall(mem, query, k=k)
+        pdm_ms = (time.perf_counter() - t0) * 1000
+
+        pdm_texts = [h.text for h in pdm_hits]
+        pdm_found = expected_text in pdm_texts
+        pdm_rank = pdm_texts.index(expected_text) + 1 if pdm_found else None
+
+        # Token approximation: count chars/4 for injected context
+        pdm_tokens = sum(len(h.text) // 4 for h in pdm_hits)
+
+        # Baseline recall
+        t0 = time.perf_counter()
+        baseline_hits = _baseline_recall(_BENCHMARK_MEMORIES, query, k=k)
+        baseline_ms = (time.perf_counter() - t0) * 1000
+
+        baseline_texts = [h[0]["text"] for h in baseline_hits]
+        baseline_found = expected_text in baseline_texts
+        baseline_rank = baseline_texts.index(expected_text) + 1 if baseline_found else None
+        baseline_tokens = sum(len(h[0]["text"]) // 4 for h in baseline_hits)
+
+        scenarios.append(ScenarioResult(
+            query=query,
+            expected_memory_idx=expected_idx,
+            pdm_found=pdm_found,
+            pdm_rank=pdm_rank,
+            pdm_latency_ms=round(pdm_ms, 2),
+            baseline_found=baseline_found,
+            baseline_rank=baseline_rank,
+            baseline_latency_ms=round(baseline_ms, 2),
+            pdm_tokens_used=pdm_tokens,
+            baseline_tokens_used=baseline_tokens,
+        ))
+
+    mem.close()
+    if os.path.exists(tmp_db):
+        os.remove(tmp_db)
+
+    n = len(scenarios)
+    report = BenchmarkReport(
+        timestamp=datetime.now(tz=timezone.utc).isoformat(),
+        total_scenarios=n,
+        pdm_accuracy=sum(s.pdm_found for s in scenarios) / n,
+        baseline_accuracy=sum(s.baseline_found for s in scenarios) / n,
+        pdm_avg_latency_ms=round(sum(s.pdm_latency_ms for s in scenarios) / n, 2),
+        baseline_avg_latency_ms=round(sum(s.baseline_latency_ms for s in scenarios) / n, 2),
+        pdm_avg_tokens=round(sum(s.pdm_tokens_used for s in scenarios) / n, 1),
+        baseline_avg_tokens=round(sum(s.baseline_tokens_used for s in scenarios) / n, 1),
+        pdm_memory_bytes=db_size,
+        baseline_memory_bytes=baseline_raw_size,
+        scenarios=scenarios,
+    )
+
+    if output:
+        with open(output, "w") as f:
+            json.dump(asdict(report), f, indent=2)
+        print(f"Results saved to {output}")
+
+    return report
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="PDM Benchmark Harness — PDM vs baseline keyword RAG"
+    )
+    parser.add_argument("--quick", action="store_true", help="Run only 5 scenarios (smoke test)")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed (default: 42)")
+    parser.add_argument("--k", type=int, default=3, help="Top-k memories per query (default: 3)")
+    parser.add_argument("--output", type=str, help="Save results as JSON to this path")
+    args = parser.parse_args()
+
+    print("Running PDM Benchmark Harness…\n")
+    report = run_benchmark(quick=args.quick, seed=args.seed, k=args.k, output=args.output)
+    print(report.render_table())
+    print(f"\nPDM accuracy:      {report.pdm_accuracy*100:.1f}%")
+    print(f"Baseline accuracy: {report.baseline_accuracy*100:.1f}%")
+
+
+if __name__ == "__main__":
+    main()

pdm_memory/tools/cli.py

@@ -0,0 +1,207 @@
+"""
+PDM CLI Tool — Task 5.3
+
+Command-line utility for inspecting and managing PDM memory stores.
+
+Usage:
+    pdm-cli list-memories --store ./my_app.db
+    pdm-cli list-memories --store ./my_app.db --min-pressure 50 --user alice
+    pdm-cli explain <memory_id> --store ./my_app.db
+    pdm-cli decay --store ./my_app.db --dry-run
+    pdm-cli stats --store ./my_app.db
+    pdm-cli drawers --store ./my_app.db
+
+Requires no extra packages (stdlib only, uses the SDK itself).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    with Memory(store=args.store, user=args.user) as mem:
+        records = mem._storage.list(
+            user=args.user,
+            limit=args.limit,
+            min_pressure=args.min_pressure,
+            drawer=args.drawer or None,
+        )
+        if not records:
+            print("No memories found.")
+            return
+
+        print(f"{'#':<4} {'ID':<10} {'P':>6} {'Spike':>6} {'Tags':<35} {'Text'}")
+        print("-" * 100)
+        for i, r in enumerate(records, 1):
+            tags_str = ", ".join(r.intent_tags[:3])
+            text_preview = r.compressed_fact[:60].replace("\n", " ")
+            print(
+                f"{i:<4} {r.id[:8]:<10} {r.p_magnitude:>6.1f} {(r.effective_spike or 0):>6.1f} "
+                f"{tags_str:<35} {text_preview}"
+            )
+        print(f"\nTotal: {len(records)} memories")
+
+
+def cmd_explain(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    with Memory(store=args.store, user=args.user) as mem:
+        try:
+            report = mem.explain(args.memory_id, query=args.query or None)
+            print(report.render())
+        except KeyError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+
+def cmd_decay(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    with Memory(store=args.store, user=args.user) as mem:
+        counts = mem.decay(dry_run=args.dry_run)
+        mode = " [DRY RUN — no changes written]" if args.dry_run else ""
+        print(f"Decay complete{mode}:")
+        print(f"  Decayed (pressure reduced):  {counts['decayed']}")
+        print(f"  Deleted (pressure < 30):     {counts['deleted']}")
+        print(f"  Skipped (within persistence): {counts['skipped']}")
+
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    with Memory(store=args.store, user=args.user) as mem:
+        total = mem.count()
+        drawers = mem.list_drawers()
+        records = mem._storage.list(user=args.user, limit=10_000)
+
+        if records:
+            pressures = [r.p_magnitude for r in records]
+            avg_p = sum(pressures) / len(pressures)
+            max_p = max(pressures)
+            min_p = min(pressures)
+        else:
+            avg_p = max_p = min_p = 0.0
+
+        print(f"PDM Memory Store: {args.store}")
+        print(f"User:             {args.user}")
+        print(f"Total memories:   {total}")
+        print(f"Avg pressure:     {avg_p:.1f}")
+        print(f"Max pressure:     {max_p:.1f}")
+        print(f"Min pressure:     {min_p:.1f}")
+        print(f"\nDrawers ({len(drawers)}):")
+        for d in drawers:
+            print(f"  {d.domain:<30} {d.signature_count:>5} memories  avg_P={d.avg_pressure:.1f}")
+
+
+def cmd_drawers(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    with Memory(store=args.store, user=args.user) as mem:
+        drawers = mem.list_drawers()
+        if not drawers:
+            print("No drawers found.")
+            return
+        print(f"{'Drawer':<35} {'Memories':>10} {'Avg Pressure':>15}")
+        print("-" * 64)
+        for d in drawers:
+            print(f"{d.domain:<35} {d.signature_count:>10} {d.avg_pressure:>15.1f}")
+
+
+def cmd_sync(args: argparse.Namespace) -> None:
+    from pdm_memory import Memory
+
+    if not args.token:
+        print("Error: --token is required for sync.", file=sys.stderr)
+        sys.exit(1)
+
+    with Memory(store=args.store, user=args.user) as mem:
+        report = mem.sync(
+            direction=args.direction,
+            cloud_url=args.cloud_url,
+            token=args.token,
+        )
+        print(f"Sync complete: {report}")
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    # Parser for root/global options
+    parser = argparse.ArgumentParser(
+        prog="pdm-cli",
+        description="PDM Memory CLI — inspect and manage local memory stores",
+    )
+    parser.add_argument(
+        "--store", default="./pdm_memory.db",
+        help="Path to SQLite .db file (default: ./pdm_memory.db)"
+    )
+    parser.add_argument(
+        "--user", default="default",
+        help="User identifier to scope queries (default: default)"
+    )
+
+    # Parent parser for subparsers to inherit store/user without overriding with defaults
+    sub_parent_parser = argparse.ArgumentParser(add_help=False)
+    sub_parent_parser.add_argument(
+        "--store", default=argparse.SUPPRESS,
+        help="Path to SQLite .db file"
+    )
+    sub_parent_parser.add_argument(
+        "--user", default=argparse.SUPPRESS,
+        help="User identifier to scope queries"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+    subparsers.required = True
+
+    # list-memories
+    p_list = subparsers.add_parser("list-memories", parents=[sub_parent_parser], help="List stored memories")
+    p_list.add_argument("--min-pressure", type=float, default=0.0, metavar="P")
+    p_list.add_argument("--limit", type=int, default=50)
+    p_list.add_argument("--drawer", type=str, default=None)
+    p_list.set_defaults(func=cmd_list)
+
+    # explain
+    p_explain = subparsers.add_parser("explain", parents=[sub_parent_parser], help="Explain a specific memory's pressure")
+    p_explain.add_argument("memory_id", help="Memory UUID (or first 8 chars)")
+    p_explain.add_argument("--query", type=str, default=None, help="Optional query for resonance breakdown")
+    p_explain.set_defaults(func=cmd_explain)
+
+    # decay
+    p_decay = subparsers.add_parser("decay", parents=[sub_parent_parser], help="Trigger a decay pass")
+    p_decay.add_argument("--dry-run", action="store_true", help="Preview without writing")
+    p_decay.set_defaults(func=cmd_decay)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", parents=[sub_parent_parser], help="Show store statistics")
+    p_stats.set_defaults(func=cmd_stats)
+
+    # drawers
+    p_drawers = subparsers.add_parser("drawers", parents=[sub_parent_parser], help="List all drawers")
+    p_drawers.set_defaults(func=cmd_drawers)
+
+    # sync
+    p_sync = subparsers.add_parser("sync", parents=[sub_parent_parser], help="Sync local store with AZUS cloud")
+    p_sync.add_argument("--direction", choices=["push", "pull", "bidirectional"], default="push")
+    p_sync.add_argument("--token", type=str, default=None, help="JWT access token")
+    p_sync.add_argument("--cloud-url", type=str, default="https://api.azus.ai")
+    p_sync.set_defaults(func=cmd_sync)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()