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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/PKG-INFO +263 -20
  2. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/README.md +262 -18
  3. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/__init__.py +11 -5
  4. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/auth/jwt_handler.py +11 -13
  5. pdm_memory-0.2.4/pdm_memory/bench/__init__.py +1 -0
  6. pdm_memory-0.2.4/pdm_memory/bench/__main__.py +5 -0
  7. pdm_memory-0.2.4/pdm_memory/bench/correctability/__init__.py +1 -0
  8. pdm_memory-0.2.4/pdm_memory/bench/correctability/ablation.py +86 -0
  9. pdm_memory-0.2.4/pdm_memory/bench/correctability/baselines.py +229 -0
  10. pdm_memory-0.2.4/pdm_memory/bench/correctability/harness.py +335 -0
  11. pdm_memory-0.2.4/pdm_memory/bench/correctability/metrics.py +399 -0
  12. pdm_memory-0.2.4/pdm_memory/bench/correctability/scenarios.py +822 -0
  13. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/core/alignment.py +228 -32
  14. pdm_memory-0.2.4/pdm_memory/core/constraints.py +621 -0
  15. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/core/math.py +8 -10
  16. pdm_memory-0.2.4/pdm_memory/core/retrieval.py +1553 -0
  17. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/core/signature.py +35 -24
  18. pdm_memory-0.2.4/pdm_memory/examples/README.md +31 -0
  19. pdm_memory-0.2.4/pdm_memory/examples/__init__.py +12 -0
  20. pdm_memory-0.2.4/pdm_memory/examples/guarded_agent_logic.py +190 -0
  21. pdm_memory-0.2.4/pdm_memory/examples/handling_contradictions.py +160 -0
  22. pdm_memory-0.2.4/pdm_memory/examples/hello_pdm.py +145 -0
  23. pdm_memory-0.2.4/pdm_memory/examples/industrial_safety_gate.py +192 -0
  24. pdm_memory-0.2.4/pdm_memory/examples/standalone_guard.py +118 -0
  25. pdm_memory-0.2.4/pdm_memory/examples/temporal_recall_demo.py +225 -0
  26. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/ingest/__init__.py +2 -2
  27. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/ingest/auto_signature.py +7 -7
  28. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/ingest/batch.py +9 -8
  29. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/ingest/ingester.py +13 -13
  30. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/__init__.py +13 -13
  31. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/anthropic_adapter.py +5 -5
  32. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/context_manager.py +6 -7
  33. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/gemini_adapter.py +5 -5
  34. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/groq_adapter.py +5 -5
  35. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/ollama_adapter.py +5 -5
  36. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/integrations/openai_adapter.py +5 -5
  37. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/io/__init__.py +2 -1
  38. pdm_memory-0.2.4/pdm_memory/io/csv_transfer.py +76 -0
  39. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/io/json_transfer.py +7 -5
  40. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/memory.py +884 -205
  41. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/models.py +7 -7
  42. pdm_memory-0.2.4/pdm_memory/storage/base.py +195 -0
  43. pdm_memory-0.2.4/pdm_memory/storage/cloud_driver.py +962 -0
  44. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/storage/factory.py +12 -2
  45. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/storage/postgres_driver.py +222 -33
  46. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/storage/schema.py +45 -11
  47. pdm_memory-0.2.4/pdm_memory/storage/sqlite_driver.py +676 -0
  48. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/sync.py +2 -0
  49. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/bench.py +128 -43
  50. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/cli.py +113 -17
  51. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/explorer_actions.py +3 -3
  52. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/server.py +45 -13
  53. pdm_memory-0.2.4/pdm_memory/types.py +37 -0
  54. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/PKG-INFO +263 -20
  55. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/SOURCES.txt +25 -1
  56. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/requires.txt +0 -1
  57. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pyproject.toml +2 -7
  58. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_alignment.py +126 -15
  59. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_cli.py +102 -11
  60. pdm_memory-0.2.4/tests/test_cloud_driver.py +748 -0
  61. pdm_memory-0.2.4/tests/test_constraints.py +282 -0
  62. pdm_memory-0.2.4/tests/test_correctability.py +393 -0
  63. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_gemini_adapter.py +1 -0
  64. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_groq_adapter.py +1 -0
  65. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_jwt_auth.py +24 -3
  66. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_math.py +7 -6
  67. pdm_memory-0.2.4/tests/test_memory.py +726 -0
  68. pdm_memory-0.2.4/tests/test_memory_hooks.py +110 -0
  69. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_ollama_adapter.py +1 -0
  70. pdm_memory-0.2.4/tests/test_postgres_driver.py +318 -0
  71. pdm_memory-0.2.4/tests/test_retrieval_diversity.py +198 -0
  72. pdm_memory-0.2.4/tests/test_sqlite_driver.py +454 -0
  73. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_storage_factory.py +72 -3
  74. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_tier2.py +73 -8
  75. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_torsion.py +76 -3
  76. pdm_memory-0.2.4/tests/test_verify_live.py +173 -0
  77. pdm_memory-0.2.0/pdm_memory/core/retrieval.py +0 -836
  78. pdm_memory-0.2.0/pdm_memory/storage/base.py +0 -134
  79. pdm_memory-0.2.0/pdm_memory/storage/cloud_driver.py +0 -506
  80. pdm_memory-0.2.0/pdm_memory/storage/sqlite_driver.py +0 -389
  81. pdm_memory-0.2.0/pdm_memory/types.py +0 -19
  82. pdm_memory-0.2.0/tests/test_cloud_driver.py +0 -164
  83. pdm_memory-0.2.0/tests/test_memory.py +0 -263
  84. pdm_memory-0.2.0/tests/test_sqlite_driver.py +0 -194
  85. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/LICENSE +0 -0
  86. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/auth/__init__.py +0 -0
  87. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/bench.py +0 -0
  88. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/core/__init__.py +0 -0
  89. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/storage/__init__.py +0 -0
  90. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/storage/errors.py +0 -0
  91. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/__init__.py +0 -0
  92. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory/tools/static/index.html +0 -0
  93. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/dependency_links.txt +0 -0
  94. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/entry_points.txt +0 -0
  95. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/pdm_memory.egg-info/top_level.txt +0 -0
  96. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/setup.cfg +0 -0
  97. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_bench.py +0 -0
  98. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_explorer_console.py +0 -0
  99. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_explorer_ui.py +0 -0
  100. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_pdm_concurrency.py +0 -0
  101. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_pdm_physics.py +0 -0
  102. {pdm_memory-0.2.0 → pdm_memory-0.2.4}/tests/test_tier3.py +1 -1
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pdm-memory
3
- Version: 0.2.0
3
+ Version: 0.2.4
4
4
  Summary: Pressure-Driven Memory (PDM) — persistent, resonance-based memory for AI apps.
5
5
  Author: Westfield Innovations LLC
6
6
  License: Elastic License 2.0 (ELv2)
@@ -166,7 +166,6 @@ Requires-Dist: tiktoken>=0.7; extra == "dev"
166
166
  Requires-Dist: google-genai>=0.1.0; extra == "dev"
167
167
  Requires-Dist: ollama>=0.2.0; extra == "dev"
168
168
  Requires-Dist: groq>=0.9.0; extra == "dev"
169
- Requires-Dist: ruff>=0.4; extra == "dev"
170
169
  Requires-Dist: fastapi>=0.110; extra == "dev"
171
170
  Requires-Dist: uvicorn[standard]>=0.27; extra == "dev"
172
171
  Dynamic: license-file
@@ -175,7 +174,6 @@ Dynamic: license-file
175
174
 
176
175
  [![PyPI](https://img.shields.io/pypi/v/pdm-memory)](https://pypi.org/project/pdm-memory/)
177
176
  [![Python](https://img.shields.io/pypi/pyversions/pdm-memory)](https://pypi.org/project/pdm-memory/)
178
- [![CI](https://github.com/westfield-innovations/pdm-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/westfield-innovations/pdm-memory/actions)
179
177
  [![License: Proprietary](https://img.shields.io/badge/License-Proprietary%20ELv2-blue)](LICENSE)
180
178
  [![Documentation](https://img.shields.io/badge/Docs-azus.ai%2Fsupport-blue)](https://azus.ai/support)
181
179
 
@@ -185,11 +183,12 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
185
183
 
186
184
  - 🔑 **Your API key.** Works with your existing Anthropic/OpenAI account.
187
185
  - 🗄️ **Your storage.** One local file. Your data never leaves your machine. Check the source — there's no phone-home in it.
186
+ - 🛡️ **Guarded agents.** Pass a rule as a string — blocks actions that contradict it. No store required. Catches contradicting facts automatically.
188
187
  - ⚡ **Ten minutes.** `pip install pdm-memory` → three lines → persistent memory.
189
188
 
190
189
  📖 **Documentation:** [azus.ai/support](https://azus.ai/support)
191
190
 
192
- **Benchmarks vs standard RAG:** [link] · Run yourself: `python -m pdm_memory.bench`
191
+ **Benchmarks vs standard RAG:** PDM wins **7 of 8** metrics — **15×** fewer tokens, **35×** less storage. One loss published. [See full methodology →](https://azus.ai/pdm/benchmarks)
193
192
 
194
193
  ---
195
194
 
@@ -199,10 +198,11 @@ Your LLM forgets everything between conversations. The standard fix — stuff a
199
198
  1. [Privacy Mode](#-privacy-mode-local-sqlite)
200
199
  2. [Ecosystem Mode](#-ecosystem-mode-azus-cloud)
201
200
  3. [LLM Adapters](#-llm-adapters)
202
- 4. [Data Ingestion](#-data-ingestion)
203
- 5. [Developer Tools](#-developer-tools)
204
- 6. [API Reference](#-api-reference)
205
- 7. [License](#-license)
201
+ 4. [Guarded Agents (GAA & Torsion)](#-guarded-agents-gaa--torsion)
202
+ 5. [Data Ingestion](#-data-ingestion)
203
+ 6. [Developer Tools](#-developer-tools)
204
+ 7. [API Reference](#-api-reference)
205
+ 8. [License](#-license)
206
206
 
207
207
  ---
208
208
 
@@ -232,7 +232,7 @@ mem = Memory(store="./my_app_memory.db")
232
232
 
233
233
  # Write: PDM assigns pressure and stores a signature.
234
234
  mem.save("User prefers metric units and short answers", source="chat",
235
- tags=["units", "formatting", "preferences"])
235
+ tags=["units", "formatting", "preferences"], p_magnitude=85)
236
236
 
237
237
  # Read: resonance retrieval — surfaces what's relevant, not just what matches.
238
238
  hits = mem.recall("how should I format the answer?", k=5)
@@ -264,7 +264,44 @@ mem = Memory(store="./private.db", store_raw=False)
264
264
 
265
265
  ## ☁️ Ecosystem Mode (AZUS Cloud)
266
266
 
267
- Connect to the AZUS Companion API to sync memories across devices and share them with the AI companion.
267
+ Connect to the **AZUS Companion API** so memories sync across devices and the companion app.
268
+
269
+ **Cloud endpoint:** default base URL is `https://api.azus.ai` (not the marketing site `https://azus.ai`). Staging: `https://staging.azus.ai`.
270
+
271
+ CloudDriver expects a Companion build that exposes the PDM SDK routes (list, batch, by-hash / by-idempotency-key, soft-delete). Older deploys still support single-row `ingest` / get / patch / hard delete only.
272
+
273
+ ### Getting your JWT access token
274
+
275
+ AZUS Cloud uses standard JWT auth. If you already have an AZUS account, sign in and use the returned `access` token as `token="..."`.
276
+
277
+ If you do not have an account yet, create one here:
278
+
279
+ - Web signup: [azus.ai/auth/register](https://azus.ai/auth/register)
280
+ - API signup: `POST https://api.azus.ai/api/v1/accounts/auth/register/`
281
+ - API login: `POST https://api.azus.ai/api/v1/accounts/auth/login/`
282
+ - Token refresh: `POST https://api.azus.ai/api/v1/accounts/token/refresh/`
283
+
284
+ Example registration flow:
285
+
286
+ ```python
287
+ import requests
288
+
289
+ r = requests.post(
290
+ "https://api.azus.ai/api/v1/accounts/auth/register/",
291
+ json={
292
+ "email": "user@example.com",
293
+ "username": "user123",
294
+ "password": "SecurePass123!",
295
+ "profile": {"first_name": "John", "last_name": "Doe"},
296
+ },
297
+ )
298
+ data = r.json()
299
+
300
+ access_token = data["tokens"]["access"]
301
+ refresh_token = data["tokens"]["refresh"]
302
+ ```
303
+
304
+ Use the returned JWTs directly with `Memory(store="cloud", ...)`:
268
305
 
269
306
  ### Connect to the Cloud
270
307
 
@@ -273,15 +310,38 @@ from pdm_memory import Memory
273
310
 
274
311
  mem = Memory(
275
312
  store="cloud",
276
- token="eyJ...", # Your AZUS JWT access token
277
- cloud_url="https://api.azus.ai",
313
+ token="eyJ...", # AZUS JWT access token
314
+ refresh_token="eyJ...", # optional — auto-refresh on 401
315
+ cloud_url="https://api.azus.ai", # optional; this is the default
316
+ user="your_username", # ownership scope for storage ops
278
317
  )
279
318
 
280
- # All save/recall operations go to the cloud.
281
- mem.save("User's team is in Kyiv (UTC+3)", tags=["location", "team", "timezone"])
319
+ # Writes use POST /api/v1/pdm/ingest; dedupe hits the by-hash API when available.
320
+ mem.save(
321
+ "User's team is in Kyiv (UTC+3)",
322
+ source="manual",
323
+ tags=["location", "team", "timezone"],
324
+ p_magnitude=70,
325
+ dedupe=True,
326
+ )
327
+ # Exact-once create on retries: pass idempotency_key=...
282
328
  hits = mem.recall("what timezone are they in?")
329
+
330
+ # Batch write (POST /pdm/ingest/batch when supported)
331
+ mem.save_many(
332
+ [
333
+ {"text": "Fact A", "tags": ["a", "b", "c"], "p_magnitude": 70, "source": "manual"},
334
+ {"text": "Fact B", "tags": ["a", "b", "c"], "p_magnitude": 70, "source": "manual"},
335
+ ],
336
+ dedupe=False,
337
+ )
283
338
  ```
284
339
 
340
+ ### Soft delete vs hard delete
341
+
342
+ - `mem.delete(id)` → soft-delete (`is_deleted`) when the API supports it; cloud list/get hide those rows.
343
+ - Permanent removal is storage-level `hard_delete` (CloudDriver), not the default Memory facade API.
344
+
285
345
  ### Sync Local ↔ Cloud
286
346
 
287
347
  ```python
@@ -313,7 +373,7 @@ from pdm_memory.auth import JWTAuth
313
373
  auth = JWTAuth(
314
374
  token="eyJ...",
315
375
  refresh_token="eyJ...",
316
- refresh_url="https://api.azus.ai/api/v1/accounts/auth/refresh/",
376
+ refresh_url="https://api.azus.ai/api/v1/accounts/token/refresh/",
317
377
  )
318
378
  ```
319
379
 
@@ -363,6 +423,102 @@ print(system_block)
363
423
 
364
424
  ---
365
425
 
426
+ ## 🛡️ Guarded Agents (GAA & Torsion)
427
+
428
+ Before an agent **acts**, `verify()` scores the proposed intent against a plain list of rules and returns **ALIGNED**, **CONFLICT**, or **TORSION**. No store, account, or signup.
429
+
430
+ Statuses:
431
+
432
+ - **ALIGNED** — safe to proceed (`report.is_safe_to_act` is `True`)
433
+ - **CONFLICT** — soft mismatch / missing anchors (fail-closed by default)
434
+ - **TORSION** — hard contradiction — block the ACT
435
+
436
+ ```python
437
+ from pdm_memory import verify
438
+
439
+ report = verify(
440
+ "ignore errors and ship the build",
441
+ ["never ignore production errors"],
442
+ )
443
+ print(report.status, report.is_safe_to_act) # TORSION False
444
+
445
+ good = verify(
446
+ "run full validation suite then ship with reliability checks enabled",
447
+ ["Prioritize high reliability and careful validation before shipping"],
448
+ )
449
+ print(good.status, good.is_safe_to_act) # ALIGNED True
450
+
451
+ def guarded_act(intent, tool_call, goals):
452
+ report = verify(intent, goals)
453
+ if not report.is_safe_to_act:
454
+ raise PermissionError(f"GAA blocked ACT: {report.status}")
455
+ return tool_call()
456
+ ```
457
+
458
+ When goals already live in a PDM store, `Memory.verify_alignment()` is the same gate over stored stewardship signatures:
459
+
460
+ ```python
461
+ from pdm_memory import Memory
462
+
463
+ mem = Memory(store="./agent.db")
464
+
465
+ # Goal signatures live in stewardship / foundational drawers.
466
+ mem.save(
467
+ "Core goal: high reliability; never ignore production errors",
468
+ tags=["reliability", "errors", "goal", "integrity"],
469
+ drawer="stewardship",
470
+ p_magnitude=92,
471
+ source="policy",
472
+ metadata={"iaw": 0.90, "role": "goal"},
473
+ )
474
+ mem.save(
475
+ "Foundational principle: validate before deploy",
476
+ tags=["validation", "deploy", "principle", "quality"],
477
+ drawer="foundational",
478
+ p_magnitude=88,
479
+ source="policy",
480
+ metadata={"iaw": 0.85, "role": "goal"},
481
+ )
482
+
483
+ # Block an action that opposes stored goals.
484
+ bad = mem.verify_alignment("ignore errors and bypass validation")
485
+ print(bad.status, bad.is_safe_to_act) # TORSION False
486
+
487
+ # Allow an action that resonates with those goals.
488
+ good = mem.verify_alignment("validate thoroughly then deploy with reliability checks")
489
+ print(good.status, good.is_safe_to_act) # ALIGNED True
490
+ ```
491
+
492
+ Catch contradicting facts already in the store:
493
+
494
+ ```python
495
+ from datetime import datetime, timezone
496
+
497
+ mem.save(
498
+ "Project Orion launch date is 2026-08-01",
499
+ tags=["orion", "launch", "deadline", "project"],
500
+ drawer="product",
501
+ p_magnitude=70,
502
+ deadline=datetime(2026, 8, 1, tzinfo=timezone.utc),
503
+ metadata={"cluster_id": "orion-launch"},
504
+ )
505
+ mem.save(
506
+ "Project Orion launch date is 2026-09-01",
507
+ tags=["orion", "launch", "deadline", "project"],
508
+ drawer="product",
509
+ p_magnitude=72,
510
+ deadline=datetime(2026, 9, 1, tzinfo=timezone.utc),
511
+ metadata={"cluster_id": "orion-launch"},
512
+ )
513
+
514
+ for report in mem.detect_torsion(threshold=0.5):
515
+ print(report.torsion_score, report.conflict_kind, report.explanation)
516
+ ```
517
+
518
+ Full walkthroughs: `python -m pdm_memory.examples.standalone_guard`, `python -m pdm_memory.examples.guarded_agent_logic` and `python -m pdm_memory.examples.handling_contradictions`.
519
+
520
+ ---
521
+
366
522
  ## 📥 Data Ingestion
367
523
 
368
524
  ### Import Legacy Data
@@ -414,6 +570,65 @@ mem.ingest(
414
570
 
415
571
  ## 🛠️ Developer Tools
416
572
 
573
+ ### Quick Start (PyPI install)
574
+
575
+ Everything below works after `pip install pdm-memory` — no repository clone required.
576
+
577
+ ```bash
578
+ pip install pdm-memory
579
+ python -m pdm_memory.examples.hello_pdm
580
+ ```
581
+
582
+ Inline smoke test:
583
+
584
+ ```bash
585
+ python -c "
586
+ from pdm_memory import Memory
587
+ mem = Memory(store='./demo.db')
588
+ mem.save('User prefers metric units and short answers', source='demo',
589
+ tags=['units', 'formatting', 'preferences'], p_magnitude=85)
590
+ for h in mem.recall('how should I format the answer?', k=3):
591
+ print(h.text, round(h.pressure, 1))
592
+ "
593
+ ```
594
+
595
+ Other PyPI-shipped tools:
596
+
597
+ ```bash
598
+ python -m pdm_memory.bench --quick # smoke benchmark (5 scenarios)
599
+ pdm-cli stats --store ./demo.db # inspect the store created above
600
+ ```
601
+
602
+ ### Example walkthroughs (bundled in PyPI)
603
+
604
+ All scripts below ship inside the wheel — run them with `python -m`:
605
+
606
+ ```bash
607
+ pip install pdm-memory
608
+ python -m pdm_memory.examples.hello_pdm # save / recall / explain
609
+ python -m pdm_memory.examples.standalone_guard # GAA: no store
610
+ python -m pdm_memory.examples.guarded_agent_logic # GAA: store-backed TORSION vs ALIGNED
611
+ python -m pdm_memory.examples.handling_contradictions # detect + reconcile torsion
612
+ python -m pdm_memory.examples.temporal_recall_demo # event_at + deadline (PDM-T)
613
+ python -m pdm_memory.examples.industrial_safety_gate # Oil Field: Auto-Discovery + heal
614
+ ```
615
+
616
+ See [`pdm_memory/examples/README.md`](pdm_memory/examples/README.md).
617
+
618
+ From a source checkout, the wrappers in [`examples/`](examples/) delegate to the same modules:
619
+
620
+ ```bash
621
+ pip install .
622
+ python examples/hello_pdm.py
623
+ ```
624
+
625
+ To run the test suite (contributors):
626
+
627
+ ```bash
628
+ pip install ".[dev]"
629
+ pytest
630
+ ```
631
+
417
632
  ### The explain Method
418
633
 
419
634
  ```python
@@ -477,6 +692,9 @@ pdm-cli decay --store ./my_app.db
477
692
  # Show stats
478
693
  pdm-cli stats --store ./my_app.db
479
694
 
695
+ # Store-free GAA — no .db required
696
+ pdm-cli verify "ignore errors and ship" --goal "never ignore production errors"
697
+
480
698
  # List drawers (categories)
481
699
  pdm-cli drawers --store ./my_app.db
482
700
 
@@ -506,15 +724,33 @@ API endpoints used by the UI: `GET /api/v1/memory-map`, `GET /api/v1/torsion`.
506
724
 
507
725
  ## 📖 API Reference
508
726
 
509
- ### `Memory(store, user, token, cloud_url, store_raw)`
727
+ ### `verify(intent_text, goals)`
728
+
729
+ Store-free Goal-Anchor Alignment. Pass a proposed action and one or more rule strings. Returns `AlignmentReport` (`ALIGNED` / `CONFLICT` / `TORSION`). No SQLite, cloud, or account.
730
+
731
+ | Arg | Description |
732
+ |-----|-------------|
733
+ | `intent_text` | Proposed action / intent to validate |
734
+ | `goals` | One rule string, or a list of rule strings |
735
+ | `torsion_threshold` | Peak torsion that escalates to `TORSION` (default `0.70`) |
736
+ | `conflict_threshold` | Soft-mismatch floor for `CONFLICT` (default `0.40`) |
737
+
738
+ Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before triggering ACT.
739
+
740
+ ### `Memory(store, user, token, refresh_token, cloud_url, store_raw)`
510
741
 
511
742
  | Method | Description |
512
743
  |--------|-------------|
513
- | `save(text, source, tags, p_magnitude, t_persistence, drawer, regime, deadline)` | Store a new memory |
744
+ | `save(text, source, tags, p_magnitude, t_persistence, drawer, regime, deadline, dedupe=True, idempotency_key=None)` | Store a memory (content dedupe and/or idempotency when storage supports it) |
745
+ | `save_many(items, dedupe=True)` → `dict` | Batch save; returns `{saved, skipped, errors}` |
514
746
  | `recall(query, k, min_pressure, search_cost, drawer, reinforce)` → `List[MemoryHit]` | Retrieve top-k relevant memories |
515
- | `reinforce(memory_id, coupling_score)` | Manually raise a memory's pressure |
747
+ | `verify_alignment(intent_text, min_pressure, k_goals, torsion_threshold)` → `AlignmentReport` | Same GAA gate against goals already stored in Memory |
748
+ | `detect_torsion(drawer, threshold)` → `List[TorsionReport]` | Find contradicting facts (Reverse Resonance) |
749
+ | `reinforce(memory_id, coupling_score)` | Manually raise a memory's pressure (and V-counters where supported) |
750
+ | `delete(memory_id)` → `bool` | Soft-delete when storage supports it |
516
751
  | `decay(dry_run)` → `dict` | Trigger decay pass (runs automatically on recall) |
517
752
  | `explain(memory_id, query)` → `ExplainReport` | Show why a memory has its current pressure |
753
+ | `list(limit, min_pressure, drawer, cursor_id)` → `MemoryListPage` | Keyset page of memories (storage list API on cloud) |
518
754
  | `sync(direction, token, cloud_url)` → `SyncReport` | Sync local ↔ cloud |
519
755
  | `ingest(data_source, mapping, llm_client, batch_size)` → `dict` | Import legacy data |
520
756
  | `list_drawers()` → `List[DrawerInfo]` | List memory categories |
@@ -556,11 +792,18 @@ from pdm_memory.storage.base import BaseStorage
556
792
 
557
793
  class MyPostgresStorage(BaseStorage):
558
794
  def save(self, sig): ...
795
+ def save_batch(self, sigs): ...
559
796
  def get(self, memory_id, user): ...
797
+ def get_many(self, ids, user): ...
560
798
  def update(self, memory_id, **fields): ...
561
- def delete(self, memory_id, user): ...
562
- def list(self, user, limit, min_pressure, drawer): ...
799
+ def update_batch(self, updates, user): ...
800
+ def delete(self, memory_id, user): ... # soft-delete when supported
801
+ def hard_delete(self, memory_id, user): ...
802
+ def list(self, user, limit, min_pressure, drawer, cursor_id=None, include_deleted=False): ...
563
803
  def list_drawers(self, user): ...
804
+ def find_by_idempotency_key(self, key, user): ...
805
+ def find_by_hash(self, text_hash, user): ...
806
+ def ping(self): ...
564
807
 
565
808
  mem = Memory.__new__(Memory)
566
809
  mem._storage = MyPostgresStorage(...)