pdm-memory 0.2.4__tar.gz → 0.2.5__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 (124) hide show
  1. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/PKG-INFO +177 -17
  2. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/README.md +175 -16
  3. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/__init__.py +20 -4
  4. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/alignment.py +12 -0
  5. pdm_memory-0.2.5/pdm_memory/core/field_scoped_retrieval.py +180 -0
  6. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/math.py +121 -9
  7. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/retrieval.py +8 -4
  8. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/signature.py +55 -3
  9. pdm_memory-0.2.5/pdm_memory/event_log.py +904 -0
  10. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/README.md +4 -0
  11. pdm_memory-0.2.5/pdm_memory/examples/field_state_demo.py +213 -0
  12. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/guarded_agent_logic.py +1 -1
  13. pdm_memory-0.2.5/pdm_memory/geopass.py +279 -0
  14. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/memory.py +652 -45
  15. pdm_memory-0.2.5/pdm_memory/models.py +719 -0
  16. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/cloud_driver.py +763 -10
  17. pdm_memory-0.2.5/pdm_memory/storage/errors.py +50 -0
  18. pdm_memory-0.2.5/pdm_memory/storage/event_hash.py +347 -0
  19. pdm_memory-0.2.5/pdm_memory/storage/event_store.py +863 -0
  20. pdm_memory-0.2.5/pdm_memory/storage/event_sync.py +333 -0
  21. pdm_memory-0.2.5/pdm_memory/storage/eventful_postgres.py +39 -0
  22. pdm_memory-0.2.5/pdm_memory/storage/eventful_sqlite.py +99 -0
  23. pdm_memory-0.2.5/pdm_memory/storage/events.py +991 -0
  24. pdm_memory-0.2.5/pdm_memory/storage/field_store.py +1053 -0
  25. pdm_memory-0.2.5/pdm_memory/storage/fields.py +581 -0
  26. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/schema.py +3 -3
  27. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/cli.py +42 -17
  28. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/explorer_actions.py +18 -4
  29. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/server.py +5 -4
  30. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/PKG-INFO +177 -17
  31. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/SOURCES.txt +28 -0
  32. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/requires.txt +1 -0
  33. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pyproject.toml +2 -1
  34. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_alignment.py +21 -1
  35. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_cli.py +6 -1
  36. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_cloud_driver.py +1 -1
  37. pdm_memory-0.2.5/tests/test_cloud_events.py +292 -0
  38. pdm_memory-0.2.5/tests/test_cloud_fields.py +558 -0
  39. pdm_memory-0.2.5/tests/test_contrary_evidence.py +144 -0
  40. pdm_memory-0.2.5/tests/test_current_resolution.py +120 -0
  41. pdm_memory-0.2.5/tests/test_event_layer_parity.py +423 -0
  42. pdm_memory-0.2.5/tests/test_evidence_layer_regressions.py +672 -0
  43. pdm_memory-0.2.5/tests/test_extract_signatures.py +146 -0
  44. pdm_memory-0.2.5/tests/test_field_memberships.py +662 -0
  45. pdm_memory-0.2.5/tests/test_field_state.py +221 -0
  46. pdm_memory-0.2.5/tests/test_geopass.py +242 -0
  47. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_math.py +106 -0
  48. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_memory.py +137 -0
  49. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_pdm_physics.py +7 -4
  50. pdm_memory-0.2.5/tests/test_postgres_live.py +220 -0
  51. pdm_memory-0.2.5/tests/test_projection.py +301 -0
  52. pdm_memory-0.2.5/tests/test_relationship_state.py +192 -0
  53. pdm_memory-0.2.5/tests/test_review24_followup.py +339 -0
  54. pdm_memory-0.2.5/tests/test_source_events.py +772 -0
  55. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_storage_factory.py +1 -1
  56. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_tier2.py +3 -3
  57. pdm_memory-0.2.5/tests/test_trajectory.py +247 -0
  58. pdm_memory-0.2.4/pdm_memory/models.py +0 -128
  59. pdm_memory-0.2.4/pdm_memory/storage/errors.py +0 -26
  60. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/LICENSE +0 -0
  61. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/auth/__init__.py +0 -0
  62. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/auth/jwt_handler.py +0 -0
  63. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/__init__.py +0 -0
  64. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/__main__.py +0 -0
  65. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/__init__.py +0 -0
  66. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/ablation.py +0 -0
  67. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/baselines.py +0 -0
  68. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/harness.py +0 -0
  69. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/metrics.py +0 -0
  70. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/scenarios.py +0 -0
  71. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench.py +0 -0
  72. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/__init__.py +0 -0
  73. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/constraints.py +0 -0
  74. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/__init__.py +0 -0
  75. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/handling_contradictions.py +0 -0
  76. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/hello_pdm.py +0 -0
  77. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/industrial_safety_gate.py +0 -0
  78. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/standalone_guard.py +0 -0
  79. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/temporal_recall_demo.py +0 -0
  80. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/__init__.py +0 -0
  81. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/auto_signature.py +0 -0
  82. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/batch.py +0 -0
  83. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/ingester.py +0 -0
  84. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/__init__.py +0 -0
  85. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/anthropic_adapter.py +0 -0
  86. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/context_manager.py +0 -0
  87. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/gemini_adapter.py +0 -0
  88. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/groq_adapter.py +0 -0
  89. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/ollama_adapter.py +0 -0
  90. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/openai_adapter.py +0 -0
  91. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/__init__.py +0 -0
  92. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/csv_transfer.py +0 -0
  93. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/json_transfer.py +0 -0
  94. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/__init__.py +0 -0
  95. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/base.py +0 -0
  96. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/factory.py +0 -0
  97. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/postgres_driver.py +0 -0
  98. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/sqlite_driver.py +0 -0
  99. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/sync.py +0 -0
  100. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/__init__.py +0 -0
  101. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/bench.py +0 -0
  102. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/static/index.html +0 -0
  103. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/types.py +0 -0
  104. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/dependency_links.txt +0 -0
  105. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/entry_points.txt +0 -0
  106. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/top_level.txt +0 -0
  107. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/setup.cfg +0 -0
  108. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_bench.py +0 -0
  109. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_constraints.py +0 -0
  110. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_correctability.py +0 -0
  111. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_explorer_console.py +0 -0
  112. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_explorer_ui.py +0 -0
  113. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_gemini_adapter.py +0 -0
  114. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_groq_adapter.py +0 -0
  115. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_jwt_auth.py +0 -0
  116. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_memory_hooks.py +0 -0
  117. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_ollama_adapter.py +0 -0
  118. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_pdm_concurrency.py +0 -0
  119. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_postgres_driver.py +0 -0
  120. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_retrieval_diversity.py +0 -0
  121. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_sqlite_driver.py +0 -0
  122. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_tier3.py +0 -0
  123. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_torsion.py +0 -0
  124. {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_verify_live.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pdm-memory
3
- Version: 0.2.4
3
+ Version: 0.2.5
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)
@@ -168,6 +168,7 @@ Requires-Dist: ollama>=0.2.0; extra == "dev"
168
168
  Requires-Dist: groq>=0.9.0; extra == "dev"
169
169
  Requires-Dist: fastapi>=0.110; extra == "dev"
170
170
  Requires-Dist: uvicorn[standard]>=0.27; extra == "dev"
171
+ Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
171
172
  Dynamic: license-file
172
173
 
173
174
  # PDM — Memory for AI Apps That Works Like Memory
@@ -228,11 +229,13 @@ pip install "pdm-memory[all]"
228
229
  from pdm_memory import Memory
229
230
 
230
231
  # One line to start. The .db file is created automatically.
231
- mem = Memory(store="./my_app_memory.db")
232
+ mem = Memory(store="./my_app_memory.db", user="alice")
232
233
 
233
234
  # Write: PDM assigns pressure and stores a signature.
234
- mem.save("User prefers metric units and short answers", source="chat",
235
- tags=["units", "formatting", "preferences"], p_magnitude=85)
235
+ # Optional shape: ephemeral (2h) / behavioral (90d) / structural (∞).
236
+ mem.save("User prefers metric units and short answers", source="manual",
237
+ tags=["units", "formatting", "preferences"], p_magnitude=85,
238
+ shape="behavioral")
236
239
 
237
240
  # Read: resonance retrieval — surfaces what's relevant, not just what matches.
238
241
  hits = mem.recall("how should I format the answer?", k=5)
@@ -243,11 +246,23 @@ for h in hits:
243
246
  # Reinforce a memory manually (recall() does this automatically).
244
247
  mem.reinforce(hits[0].id)
245
248
 
249
+ # Contrary evidence: lower active pressure/V without rewriting the stored fact.
250
+ result = mem.apply_contrary_evidence(
251
+ hits[0].id,
252
+ "User prefers imperial units",
253
+ evidence_tags=["units", "formatting", "preferences"],
254
+ )
255
+ print(result.p_before, "→", result.p_after)
256
+
246
257
  # Inspect why a memory surfaced.
247
258
  report = mem.explain(hits[0].id, query="how should I format the answer?")
248
259
  print(report.render())
249
260
 
250
- # Decay runs automatically on each recall(). Manual trigger:
261
+ # Live decay snapshot for one memory (read-only):
262
+ snap = mem.decay_at(hits[0].id)
263
+ print(snap.shape, snap.half_life_days, snap.p_effective)
264
+
265
+ # Store-wide soft-delete of memories below the live P_effective threshold:
251
266
  counts = mem.decay()
252
267
  print(f"Decayed: {counts['decayed']}, Deleted: {counts['deleted']}")
253
268
  ```
@@ -257,7 +272,7 @@ print(f"Decayed: {counts['decayed']}, Deleted: {counts['deleted']}")
257
272
  Store only SHA-256 hashes of memory text — the content never touches disk:
258
273
 
259
274
  ```python
260
- mem = Memory(store="./private.db", store_raw=False)
275
+ mem = Memory(store="./private.db", user="alice", store_raw=False)
261
276
  ```
262
277
 
263
278
  ---
@@ -301,7 +316,7 @@ access_token = data["tokens"]["access"]
301
316
  refresh_token = data["tokens"]["refresh"]
302
317
  ```
303
318
 
304
- Use the returned JWTs directly with `Memory(store="cloud", ...)`:
319
+ Use the returned JWTs directly with `Memory(store="cloud", user=..., ...)`:
305
320
 
306
321
  ### Connect to the Cloud
307
322
 
@@ -324,6 +339,8 @@ mem.save(
324
339
  p_magnitude=70,
325
340
  dedupe=True,
326
341
  )
342
+ # A cloud store requires at least 3 tags per memory (ValueError before any
343
+ # request otherwise); a local store accepts fewer.
327
344
  # Exact-once create on retries: pass idempotency_key=...
328
345
  hits = mem.recall("what timezone are they in?")
329
346
 
@@ -342,11 +359,149 @@ mem.save_many(
342
359
  - `mem.delete(id)` → soft-delete (`is_deleted`) when the API supports it; cloud list/get hide those rows.
343
360
  - Permanent removal is storage-level `hard_delete` (CloudDriver), not the default Memory facade API.
344
361
 
362
+ ### Field State
363
+
364
+ The reconciled state of a bounded field — who belongs to it, how they are
365
+ connected, and what is visible in it — at a moment.
366
+
367
+ ```python
368
+ from datetime import datetime, timezone
369
+
370
+ # As it stands now. The moment is left out of the request on purpose, so the
371
+ # server answers from its own clock rather than yours.
372
+ state = mem.current_state("westfield")
373
+
374
+ # As it stood then. Must carry a timezone, and must not be in the future.
375
+ state = mem.state_at("westfield", datetime(2026, 3, 1, 12, tzinfo=timezone.utc))
376
+
377
+ state.field_memberships # standing in the field, with the intervals it held
378
+ state.relationships # edges, each with how current its channel reads
379
+ state.entities # what this observer may reveal, one keyset page
380
+
381
+ # Nested fields match by prefix: "westfield" covers "westfield/dqs".
382
+ state = mem.current_state("westfield/dqs")
383
+
384
+ # Paging: follow the cursor and drop the envelope, which does not change
385
+ # between pages.
386
+ page = mem.current_state("westfield", cursor=state.entities_next_cursor, envelope=False)
387
+ ```
388
+
389
+ - **Cloud only.** Fields and memberships do not exist in the local schema, so
390
+ both calls raise in privacy mode rather than inventing a second data model.
391
+ - **Every item declares its own provenance.** `state_type` is `"measured"` or
392
+ `"projected"` on each item, never inferred from where it sits. A payload with
393
+ an untagged item is rejected rather than guessed at.
394
+ - **`envelope_included=False` means the envelope is absent, not empty.** The
395
+ fields are omitted rather than returned as `[]`, so a page-2 response can
396
+ never be read as a statement about the field.
397
+ - **Results are filtered to what the observer may reveal.** There is no
398
+ unfiltered mode, and permission resolves against now — a revoked grant does
399
+ not reopen last year.
400
+
401
+ ### Relationships
402
+
403
+ `EventLog.link(...)` records that two entities stood in some relation; the
404
+ methods below read and reinforce that link's channel over time.
405
+
406
+ ```python
407
+ from pdm_memory import Memory
408
+ from pdm_memory.event_log import EventLog
409
+
410
+ mem = Memory(store="cloud", user="alice", token="eyJ...")
411
+ log = EventLog(mem)
412
+
413
+ relationship_id = log.link("subject:1", "entity:abc-123", "colleague")
414
+
415
+ # Point-in-time state of the pair — which links were live, which channel
416
+ # measurements applied, and (only within the channel's own recency window)
417
+ # the current resolution vector. at_time omitted means now.
418
+ state = mem.relationship_state("subject:1", "entity:abc-123")
419
+ state.relationships # the live/historical link rows for this pair
420
+ state.channels # {domain: channel snapshot}, by domain
421
+ state.current_resolution_by_domain # None outside the recency window
422
+ state.current_resolution_reason # "past_moment" when it is None
423
+
424
+ # Cite an existing fact as reinforcing or contrary evidence for the link's
425
+ # channel. No bare number: the citation itself is the input.
426
+ from pdm_memory.storage.fields import RelationshipRecord
427
+
428
+ relationship = RelationshipRecord(id=relationship_id, source_entity_id="subject:1",
429
+ target_entity_id="entity:abc-123", relationship_type="colleague")
430
+ log.reinforce(relationship, evidence="sig-1") # or a SignatureRecord/SourceEventRecord
431
+ log.apply_contrary_evidence(relationship, evidence="sig-2")
432
+ ```
433
+
434
+ - **Cloud only**, same as Field State — `RelationshipChannel` and its
435
+ evidence log live only in Companion.
436
+ - **Dispatch by target type**, not by guessing at a string. `reinforce`/
437
+ `apply_contrary_evidence` route to the relationship-evidence endpoint only
438
+ when *target* is a `RelationshipRecord`; a bare string id or a
439
+ `SignatureRecord` goes to the existing, unchanged `Memory.reinforce()` /
440
+ `Memory.apply_contrary_evidence()` — the same methods and behaviour as
441
+ before this feature existed.
442
+ - **Resubmitting the same evidence is refused** (`CloudConflictError`,
443
+ `error_code="EVIDENCE_ALREADY_APPLIED"`), not silently counted twice.
444
+
445
+ | This document's naming | SDK method |
446
+ |---|---|
447
+ | Point-in-time relationship state | `Memory.relationship_state(source, target, at_time=None, domain=None)` |
448
+ | Reinforcing evidence, on a link | `EventLog.reinforce(relationship_record, evidence)` |
449
+ | Contrary evidence, on a link | `EventLog.apply_contrary_evidence(relationship_record, evidence)` |
450
+ | Reinforcing evidence, on a memory (unchanged) | `EventLog.reinforce(memory_id_or_record)` → `Memory.reinforce` |
451
+ | Contrary evidence, on a memory (unchanged) | `EventLog.apply_contrary_evidence(memory_id_or_record, evidence)` → `Memory.apply_contrary_evidence` |
452
+
453
+ ### Projections
454
+
455
+ A forward fan of where your channel is heading, and — once time has passed —
456
+ how it turned out.
457
+
458
+ ```python
459
+ from datetime import datetime, timezone
460
+
461
+ fan = mem.project() # the fan now; nothing is written
462
+ fan = mem.project(horizon_days=30) # narrower window, clamped to the server's reach
463
+ fan = mem.project(record=True) # persist it so it can be scored later
464
+
465
+ for branch in fan.branches:
466
+ branch.state_type # always "projected"
467
+ branch.confidence_band["weight"] # this branch's share of the fan
468
+ branch.timing_range # {"start", "end"} — a window, never a point
469
+ branch.invalidation_conditions # what would make it wrong
470
+
471
+ # Later: settle one recorded branch against what actually happened.
472
+ settled = mem.record_outcome(
473
+ fan.projection_ids[0],
474
+ observed_at=datetime.now(timezone.utc),
475
+ connection_geometry="correct", # "correct" | "partial" | "incorrect"
476
+ meaning_propagation="partial",
477
+ )
478
+ settled.outcome.timing # "early" | "within" | "late" — derived by the server
479
+
480
+ mem.projection(settled.id) # read it back, with its outcome
481
+ ```
482
+
483
+ - **Cloud only.** The fan is built from the observer's channel, which lives
484
+ in Companion.
485
+ - **A different type from a field state.** `ProjectionFan` and
486
+ `RecordedProjection` share no base class with `FieldStateSnapshot`, and a
487
+ payload whose items do not say `state_type="projected"` is refused rather
488
+ than typed as a projection.
489
+ - **Not field-scoped.** Spec §7 names `project(field_id, horizon,
490
+ constraints)`; the fan is built per domain, not per field, so there is no
491
+ `field_id` to pass, and `horizon_days` is the one constraint the server honours.
492
+ - **Recorded once a day.** With `record=True`, `projection_ids` is empty on a
493
+ repeat the same UTC day — that fan is already on file.
494
+ - **Settles once.** A second outcome raises `CloudConflictError`
495
+ (`error_code="ALREADY_SETTLED"`); an outcome observed before the projection
496
+ was made raises `CloudStorageError` with `status_code=422`; someone else's
497
+ projection reads as `CloudNotFoundError`. `timing` is never sent — the
498
+ server derives it from `observed_at`.
499
+
345
500
  ### Sync Local ↔ Cloud
346
501
 
347
502
  ```python
348
503
  # Start with a local store
349
- local_mem = Memory(store="./local.db")
504
+ local_mem = Memory(store="./local.db", user="alice")
350
505
  local_mem.save("Local preference", tags=["pref", "local", "test"])
351
506
 
352
507
  # Push local memories to cloud
@@ -389,7 +544,7 @@ The wrapper is the demo; the primitives are the product. Most developers start h
389
544
  from pdm_memory import Memory
390
545
  from pdm_memory.integrations import wrap_openai
391
546
 
392
- mem = Memory(store="./my_app.db")
547
+ mem = Memory(store="./my_app.db", user="alice")
393
548
  client = wrap_openai(api_key="sk-...", memory=mem)
394
549
 
395
550
  # Memory is handled completely invisibly:
@@ -460,7 +615,7 @@ When goals already live in a PDM store, `Memory.verify_alignment()` is the same
460
615
  ```python
461
616
  from pdm_memory import Memory
462
617
 
463
- mem = Memory(store="./agent.db")
618
+ mem = Memory(store="./agent.db", user="alice")
464
619
 
465
620
  # Goal signatures live in stewardship / foundational drawers.
466
621
  mem.save(
@@ -584,7 +739,7 @@ Inline smoke test:
584
739
  ```bash
585
740
  python -c "
586
741
  from pdm_memory import Memory
587
- mem = Memory(store='./demo.db')
742
+ mem = Memory(store='./demo.db', user='alice')
588
743
  mem.save('User prefers metric units and short answers', source='demo',
589
744
  tags=['units', 'formatting', 'preferences'], p_magnitude=85)
590
745
  for h in mem.recall('how should I format the answer?', k=3):
@@ -737,18 +892,23 @@ Store-free Goal-Anchor Alignment. Pass a proposed action and one or more rule st
737
892
 
738
893
  Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before triggering ACT.
739
894
 
740
- ### `Memory(store, user, token, refresh_token, cloud_url, store_raw)`
895
+ ### `Memory(store, *, user, token, refresh_token, cloud_url, store_raw)`
896
+
897
+ `user` is required and keyword-only. Against a cloud store it must be the username the token belongs to: the server takes the owner from the token and refuses a payload naming anyone else.
741
898
 
742
899
  | Method | Description |
743
900
  |--------|-------------|
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}` |
901
+ | `save(text, source, tags, p_magnitude, t_persistence, drawer, regime, deadline, shape=None, dedupe=True, idempotency_key=None)` | Store a memory; optional `shape` (`ephemeral` / `behavioral` / `structural`) sets half-life via `metadata[memory_shape]` |
902
+ | `save_many(items, dedupe=True)` → `dict` | Batch save; returns `{saved, skipped, errors}` (items may include `shape`) |
746
903
  | `recall(query, k, min_pressure, search_cost, drawer, reinforce)` → `List[MemoryHit]` | Retrieve top-k relevant memories |
747
904
  | `verify_alignment(intent_text, min_pressure, k_goals, torsion_threshold)` → `AlignmentReport` | Same GAA gate against goals already stored in Memory |
748
905
  | `detect_torsion(drawer, threshold)` → `List[TorsionReport]` | Find contradicting facts (Reverse Resonance) |
749
906
  | `reinforce(memory_id, coupling_score)` | Manually raise a memory's pressure (and V-counters where supported) |
907
+ | `penalize(memory_id, coupling_score)` | Record a wrong prediction: lower P and V |
908
+ | `apply_contrary_evidence(target, evidence, …)` → `ContraryEvidenceResult` | Immediate V-miss + Δp on conflicting evidence; does not rewrite historical fact fields |
750
909
  | `delete(memory_id)` → `bool` | Soft-delete when storage supports it |
751
- | `decay(dry_run)` → `dict` | Trigger decay pass (runs automatically on recall) |
910
+ | `decay_at(signature, now=None)` → `DecaySnapshot` | Live shape-aware decay metrics for one memory (read-only) |
911
+ | `decay(dry_run=False)` → `dict` | Soft-delete signatures whose live `P_effective` is below threshold |
752
912
  | `explain(memory_id, query)` → `ExplainReport` | Show why a memory has its current pressure |
753
913
  | `list(limit, min_pressure, drawer, cursor_id)` → `MemoryListPage` | Keyset page of memories (storage list API on cloud) |
754
914
  | `sync(direction, token, cloud_url)` → `SyncReport` | Sync local ↔ cloud |
@@ -775,11 +935,11 @@ Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before trigge
775
935
 
776
936
  **Pressure** — every memory has a p_magnitude (0–100). Important, frequently-used memories stay strong. Unused ones decay. You control the baseline; the system adjusts dynamically.
777
937
 
778
- **Decay** — computed at recall time based on elapsed days vs. domain-specific half-lives. No scheduler required (Celery-free). Market signals decay in 1 day; core facts persist for a year.
938
+ **Decay** — live `P_effective` uses an exponential half-life at recall/explain time (stored `p_magnitude` is not rewritten on read). Domain half-lives still apply (market signals ~1 day; core facts ~1 year). When a **memory shape** is set (`ephemeral` / `behavioral` / `structural`), it overrides domain: 2 hours / 90 days / ∞. `mem.decay_at(id)` returns a live snapshot; `mem.decay()` soft-deletes signatures below the live threshold (rows are hidden, not erased).
779
939
 
780
940
  **Retrieval (TAS)** — Threshold-Adjustment Search lowers the pressure threshold based on query uncertainty (search_cost). Then coupling scores rank memories by tag overlap, domain, regime, and pressure proximity. The most resonant memories surface first.
781
941
 
782
- **Validation Coefficient (V)** — Laplace-smoothed accuracy tracker. Memories that prove predictively useful grow stronger; ones that mislead decay faster.
942
+ **Validation Coefficient (V)** — Laplace-smoothed accuracy tracker. Memories that prove predictively useful grow stronger; ones that mislead lose authority. Use `reinforce` / `penalize`, or `apply_contrary_evidence` when new facts conflict with a stored claim.
783
943
 
784
944
  ---
785
945
 
@@ -56,11 +56,13 @@ pip install "pdm-memory[all]"
56
56
  from pdm_memory import Memory
57
57
 
58
58
  # One line to start. The .db file is created automatically.
59
- mem = Memory(store="./my_app_memory.db")
59
+ mem = Memory(store="./my_app_memory.db", user="alice")
60
60
 
61
61
  # Write: PDM assigns pressure and stores a signature.
62
- mem.save("User prefers metric units and short answers", source="chat",
63
- tags=["units", "formatting", "preferences"], p_magnitude=85)
62
+ # Optional shape: ephemeral (2h) / behavioral (90d) / structural (∞).
63
+ mem.save("User prefers metric units and short answers", source="manual",
64
+ tags=["units", "formatting", "preferences"], p_magnitude=85,
65
+ shape="behavioral")
64
66
 
65
67
  # Read: resonance retrieval — surfaces what's relevant, not just what matches.
66
68
  hits = mem.recall("how should I format the answer?", k=5)
@@ -71,11 +73,23 @@ for h in hits:
71
73
  # Reinforce a memory manually (recall() does this automatically).
72
74
  mem.reinforce(hits[0].id)
73
75
 
76
+ # Contrary evidence: lower active pressure/V without rewriting the stored fact.
77
+ result = mem.apply_contrary_evidence(
78
+ hits[0].id,
79
+ "User prefers imperial units",
80
+ evidence_tags=["units", "formatting", "preferences"],
81
+ )
82
+ print(result.p_before, "→", result.p_after)
83
+
74
84
  # Inspect why a memory surfaced.
75
85
  report = mem.explain(hits[0].id, query="how should I format the answer?")
76
86
  print(report.render())
77
87
 
78
- # Decay runs automatically on each recall(). Manual trigger:
88
+ # Live decay snapshot for one memory (read-only):
89
+ snap = mem.decay_at(hits[0].id)
90
+ print(snap.shape, snap.half_life_days, snap.p_effective)
91
+
92
+ # Store-wide soft-delete of memories below the live P_effective threshold:
79
93
  counts = mem.decay()
80
94
  print(f"Decayed: {counts['decayed']}, Deleted: {counts['deleted']}")
81
95
  ```
@@ -85,7 +99,7 @@ print(f"Decayed: {counts['decayed']}, Deleted: {counts['deleted']}")
85
99
  Store only SHA-256 hashes of memory text — the content never touches disk:
86
100
 
87
101
  ```python
88
- mem = Memory(store="./private.db", store_raw=False)
102
+ mem = Memory(store="./private.db", user="alice", store_raw=False)
89
103
  ```
90
104
 
91
105
  ---
@@ -129,7 +143,7 @@ access_token = data["tokens"]["access"]
129
143
  refresh_token = data["tokens"]["refresh"]
130
144
  ```
131
145
 
132
- Use the returned JWTs directly with `Memory(store="cloud", ...)`:
146
+ Use the returned JWTs directly with `Memory(store="cloud", user=..., ...)`:
133
147
 
134
148
  ### Connect to the Cloud
135
149
 
@@ -152,6 +166,8 @@ mem.save(
152
166
  p_magnitude=70,
153
167
  dedupe=True,
154
168
  )
169
+ # A cloud store requires at least 3 tags per memory (ValueError before any
170
+ # request otherwise); a local store accepts fewer.
155
171
  # Exact-once create on retries: pass idempotency_key=...
156
172
  hits = mem.recall("what timezone are they in?")
157
173
 
@@ -170,11 +186,149 @@ mem.save_many(
170
186
  - `mem.delete(id)` → soft-delete (`is_deleted`) when the API supports it; cloud list/get hide those rows.
171
187
  - Permanent removal is storage-level `hard_delete` (CloudDriver), not the default Memory facade API.
172
188
 
189
+ ### Field State
190
+
191
+ The reconciled state of a bounded field — who belongs to it, how they are
192
+ connected, and what is visible in it — at a moment.
193
+
194
+ ```python
195
+ from datetime import datetime, timezone
196
+
197
+ # As it stands now. The moment is left out of the request on purpose, so the
198
+ # server answers from its own clock rather than yours.
199
+ state = mem.current_state("westfield")
200
+
201
+ # As it stood then. Must carry a timezone, and must not be in the future.
202
+ state = mem.state_at("westfield", datetime(2026, 3, 1, 12, tzinfo=timezone.utc))
203
+
204
+ state.field_memberships # standing in the field, with the intervals it held
205
+ state.relationships # edges, each with how current its channel reads
206
+ state.entities # what this observer may reveal, one keyset page
207
+
208
+ # Nested fields match by prefix: "westfield" covers "westfield/dqs".
209
+ state = mem.current_state("westfield/dqs")
210
+
211
+ # Paging: follow the cursor and drop the envelope, which does not change
212
+ # between pages.
213
+ page = mem.current_state("westfield", cursor=state.entities_next_cursor, envelope=False)
214
+ ```
215
+
216
+ - **Cloud only.** Fields and memberships do not exist in the local schema, so
217
+ both calls raise in privacy mode rather than inventing a second data model.
218
+ - **Every item declares its own provenance.** `state_type` is `"measured"` or
219
+ `"projected"` on each item, never inferred from where it sits. A payload with
220
+ an untagged item is rejected rather than guessed at.
221
+ - **`envelope_included=False` means the envelope is absent, not empty.** The
222
+ fields are omitted rather than returned as `[]`, so a page-2 response can
223
+ never be read as a statement about the field.
224
+ - **Results are filtered to what the observer may reveal.** There is no
225
+ unfiltered mode, and permission resolves against now — a revoked grant does
226
+ not reopen last year.
227
+
228
+ ### Relationships
229
+
230
+ `EventLog.link(...)` records that two entities stood in some relation; the
231
+ methods below read and reinforce that link's channel over time.
232
+
233
+ ```python
234
+ from pdm_memory import Memory
235
+ from pdm_memory.event_log import EventLog
236
+
237
+ mem = Memory(store="cloud", user="alice", token="eyJ...")
238
+ log = EventLog(mem)
239
+
240
+ relationship_id = log.link("subject:1", "entity:abc-123", "colleague")
241
+
242
+ # Point-in-time state of the pair — which links were live, which channel
243
+ # measurements applied, and (only within the channel's own recency window)
244
+ # the current resolution vector. at_time omitted means now.
245
+ state = mem.relationship_state("subject:1", "entity:abc-123")
246
+ state.relationships # the live/historical link rows for this pair
247
+ state.channels # {domain: channel snapshot}, by domain
248
+ state.current_resolution_by_domain # None outside the recency window
249
+ state.current_resolution_reason # "past_moment" when it is None
250
+
251
+ # Cite an existing fact as reinforcing or contrary evidence for the link's
252
+ # channel. No bare number: the citation itself is the input.
253
+ from pdm_memory.storage.fields import RelationshipRecord
254
+
255
+ relationship = RelationshipRecord(id=relationship_id, source_entity_id="subject:1",
256
+ target_entity_id="entity:abc-123", relationship_type="colleague")
257
+ log.reinforce(relationship, evidence="sig-1") # or a SignatureRecord/SourceEventRecord
258
+ log.apply_contrary_evidence(relationship, evidence="sig-2")
259
+ ```
260
+
261
+ - **Cloud only**, same as Field State — `RelationshipChannel` and its
262
+ evidence log live only in Companion.
263
+ - **Dispatch by target type**, not by guessing at a string. `reinforce`/
264
+ `apply_contrary_evidence` route to the relationship-evidence endpoint only
265
+ when *target* is a `RelationshipRecord`; a bare string id or a
266
+ `SignatureRecord` goes to the existing, unchanged `Memory.reinforce()` /
267
+ `Memory.apply_contrary_evidence()` — the same methods and behaviour as
268
+ before this feature existed.
269
+ - **Resubmitting the same evidence is refused** (`CloudConflictError`,
270
+ `error_code="EVIDENCE_ALREADY_APPLIED"`), not silently counted twice.
271
+
272
+ | This document's naming | SDK method |
273
+ |---|---|
274
+ | Point-in-time relationship state | `Memory.relationship_state(source, target, at_time=None, domain=None)` |
275
+ | Reinforcing evidence, on a link | `EventLog.reinforce(relationship_record, evidence)` |
276
+ | Contrary evidence, on a link | `EventLog.apply_contrary_evidence(relationship_record, evidence)` |
277
+ | Reinforcing evidence, on a memory (unchanged) | `EventLog.reinforce(memory_id_or_record)` → `Memory.reinforce` |
278
+ | Contrary evidence, on a memory (unchanged) | `EventLog.apply_contrary_evidence(memory_id_or_record, evidence)` → `Memory.apply_contrary_evidence` |
279
+
280
+ ### Projections
281
+
282
+ A forward fan of where your channel is heading, and — once time has passed —
283
+ how it turned out.
284
+
285
+ ```python
286
+ from datetime import datetime, timezone
287
+
288
+ fan = mem.project() # the fan now; nothing is written
289
+ fan = mem.project(horizon_days=30) # narrower window, clamped to the server's reach
290
+ fan = mem.project(record=True) # persist it so it can be scored later
291
+
292
+ for branch in fan.branches:
293
+ branch.state_type # always "projected"
294
+ branch.confidence_band["weight"] # this branch's share of the fan
295
+ branch.timing_range # {"start", "end"} — a window, never a point
296
+ branch.invalidation_conditions # what would make it wrong
297
+
298
+ # Later: settle one recorded branch against what actually happened.
299
+ settled = mem.record_outcome(
300
+ fan.projection_ids[0],
301
+ observed_at=datetime.now(timezone.utc),
302
+ connection_geometry="correct", # "correct" | "partial" | "incorrect"
303
+ meaning_propagation="partial",
304
+ )
305
+ settled.outcome.timing # "early" | "within" | "late" — derived by the server
306
+
307
+ mem.projection(settled.id) # read it back, with its outcome
308
+ ```
309
+
310
+ - **Cloud only.** The fan is built from the observer's channel, which lives
311
+ in Companion.
312
+ - **A different type from a field state.** `ProjectionFan` and
313
+ `RecordedProjection` share no base class with `FieldStateSnapshot`, and a
314
+ payload whose items do not say `state_type="projected"` is refused rather
315
+ than typed as a projection.
316
+ - **Not field-scoped.** Spec §7 names `project(field_id, horizon,
317
+ constraints)`; the fan is built per domain, not per field, so there is no
318
+ `field_id` to pass, and `horizon_days` is the one constraint the server honours.
319
+ - **Recorded once a day.** With `record=True`, `projection_ids` is empty on a
320
+ repeat the same UTC day — that fan is already on file.
321
+ - **Settles once.** A second outcome raises `CloudConflictError`
322
+ (`error_code="ALREADY_SETTLED"`); an outcome observed before the projection
323
+ was made raises `CloudStorageError` with `status_code=422`; someone else's
324
+ projection reads as `CloudNotFoundError`. `timing` is never sent — the
325
+ server derives it from `observed_at`.
326
+
173
327
  ### Sync Local ↔ Cloud
174
328
 
175
329
  ```python
176
330
  # Start with a local store
177
- local_mem = Memory(store="./local.db")
331
+ local_mem = Memory(store="./local.db", user="alice")
178
332
  local_mem.save("Local preference", tags=["pref", "local", "test"])
179
333
 
180
334
  # Push local memories to cloud
@@ -217,7 +371,7 @@ The wrapper is the demo; the primitives are the product. Most developers start h
217
371
  from pdm_memory import Memory
218
372
  from pdm_memory.integrations import wrap_openai
219
373
 
220
- mem = Memory(store="./my_app.db")
374
+ mem = Memory(store="./my_app.db", user="alice")
221
375
  client = wrap_openai(api_key="sk-...", memory=mem)
222
376
 
223
377
  # Memory is handled completely invisibly:
@@ -288,7 +442,7 @@ When goals already live in a PDM store, `Memory.verify_alignment()` is the same
288
442
  ```python
289
443
  from pdm_memory import Memory
290
444
 
291
- mem = Memory(store="./agent.db")
445
+ mem = Memory(store="./agent.db", user="alice")
292
446
 
293
447
  # Goal signatures live in stewardship / foundational drawers.
294
448
  mem.save(
@@ -412,7 +566,7 @@ Inline smoke test:
412
566
  ```bash
413
567
  python -c "
414
568
  from pdm_memory import Memory
415
- mem = Memory(store='./demo.db')
569
+ mem = Memory(store='./demo.db', user='alice')
416
570
  mem.save('User prefers metric units and short answers', source='demo',
417
571
  tags=['units', 'formatting', 'preferences'], p_magnitude=85)
418
572
  for h in mem.recall('how should I format the answer?', k=3):
@@ -565,18 +719,23 @@ Store-free Goal-Anchor Alignment. Pass a proposed action and one or more rule st
565
719
 
566
720
  Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before triggering ACT.
567
721
 
568
- ### `Memory(store, user, token, refresh_token, cloud_url, store_raw)`
722
+ ### `Memory(store, *, user, token, refresh_token, cloud_url, store_raw)`
723
+
724
+ `user` is required and keyword-only. Against a cloud store it must be the username the token belongs to: the server takes the owner from the token and refuses a payload naming anyone else.
569
725
 
570
726
  | Method | Description |
571
727
  |--------|-------------|
572
- | `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) |
573
- | `save_many(items, dedupe=True)` → `dict` | Batch save; returns `{saved, skipped, errors}` |
728
+ | `save(text, source, tags, p_magnitude, t_persistence, drawer, regime, deadline, shape=None, dedupe=True, idempotency_key=None)` | Store a memory; optional `shape` (`ephemeral` / `behavioral` / `structural`) sets half-life via `metadata[memory_shape]` |
729
+ | `save_many(items, dedupe=True)` → `dict` | Batch save; returns `{saved, skipped, errors}` (items may include `shape`) |
574
730
  | `recall(query, k, min_pressure, search_cost, drawer, reinforce)` → `List[MemoryHit]` | Retrieve top-k relevant memories |
575
731
  | `verify_alignment(intent_text, min_pressure, k_goals, torsion_threshold)` → `AlignmentReport` | Same GAA gate against goals already stored in Memory |
576
732
  | `detect_torsion(drawer, threshold)` → `List[TorsionReport]` | Find contradicting facts (Reverse Resonance) |
577
733
  | `reinforce(memory_id, coupling_score)` | Manually raise a memory's pressure (and V-counters where supported) |
734
+ | `penalize(memory_id, coupling_score)` | Record a wrong prediction: lower P and V |
735
+ | `apply_contrary_evidence(target, evidence, …)` → `ContraryEvidenceResult` | Immediate V-miss + Δp on conflicting evidence; does not rewrite historical fact fields |
578
736
  | `delete(memory_id)` → `bool` | Soft-delete when storage supports it |
579
- | `decay(dry_run)` → `dict` | Trigger decay pass (runs automatically on recall) |
737
+ | `decay_at(signature, now=None)` → `DecaySnapshot` | Live shape-aware decay metrics for one memory (read-only) |
738
+ | `decay(dry_run=False)` → `dict` | Soft-delete signatures whose live `P_effective` is below threshold |
580
739
  | `explain(memory_id, query)` → `ExplainReport` | Show why a memory has its current pressure |
581
740
  | `list(limit, min_pressure, drawer, cursor_id)` → `MemoryListPage` | Keyset page of memories (storage list API on cloud) |
582
741
  | `sync(direction, token, cloud_url)` → `SyncReport` | Sync local ↔ cloud |
@@ -603,11 +762,11 @@ Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before trigge
603
762
 
604
763
  **Pressure** — every memory has a p_magnitude (0–100). Important, frequently-used memories stay strong. Unused ones decay. You control the baseline; the system adjusts dynamically.
605
764
 
606
- **Decay** — computed at recall time based on elapsed days vs. domain-specific half-lives. No scheduler required (Celery-free). Market signals decay in 1 day; core facts persist for a year.
765
+ **Decay** — live `P_effective` uses an exponential half-life at recall/explain time (stored `p_magnitude` is not rewritten on read). Domain half-lives still apply (market signals ~1 day; core facts ~1 year). When a **memory shape** is set (`ephemeral` / `behavioral` / `structural`), it overrides domain: 2 hours / 90 days / ∞. `mem.decay_at(id)` returns a live snapshot; `mem.decay()` soft-deletes signatures below the live threshold (rows are hidden, not erased).
607
766
 
608
767
  **Retrieval (TAS)** — Threshold-Adjustment Search lowers the pressure threshold based on query uncertainty (search_cost). Then coupling scores rank memories by tag overlap, domain, regime, and pressure proximity. The most resonant memories surface first.
609
768
 
610
- **Validation Coefficient (V)** — Laplace-smoothed accuracy tracker. Memories that prove predictively useful grow stronger; ones that mislead decay faster.
769
+ **Validation Coefficient (V)** — Laplace-smoothed accuracy tracker. Memories that prove predictively useful grow stronger; ones that mislead lose authority. Use `reinforce` / `penalize`, or `apply_contrary_evidence` when new facts conflict with a stored claim.
611
770
 
612
771
  ---
613
772
 
@@ -15,7 +15,7 @@ The public surface of the SDK:
15
15
  from pdm_memory import Memory
16
16
 
17
17
  mem = Memory(store="./my_app.db")
18
- mem.save("User prefers metric units", source="chat")
18
+ mem.save("User prefers metric units", source="manual")
19
19
  hits = mem.recall("how should I format this?", k=5)
20
20
 
21
21
  from pdm_memory.integrations import wrap_openai, wrap_anthropic
@@ -24,17 +24,33 @@ See README.md for full documentation.
24
24
  """
25
25
 
26
26
  from pdm_memory.core.alignment import verify
27
- from pdm_memory.core.signature import DrawerInfo, MemoryHit
27
+ from pdm_memory.core.math import MEMORY_SHAPE_KEY, SHAPE_HALF_LIVES
28
+ from pdm_memory.core.signature import (
29
+ ContraryEvidenceResult,
30
+ DecaySnapshot,
31
+ DrawerInfo,
32
+ MemoryHit,
33
+ )
28
34
  from pdm_memory.memory import Memory
29
- from pdm_memory.models import AlignmentReport, SurfaceReport, TorsionReport
35
+ from pdm_memory.models import (
36
+ AlignmentReport,
37
+ RelationshipChannelResolution,
38
+ SurfaceReport,
39
+ TorsionReport,
40
+ )
30
41
  from pdm_memory.storage.factory import create_storage, register_storage
31
42
 
32
- __version__ = "0.2.4"
43
+ __version__ = "0.2.5"
33
44
  __all__ = [
34
45
  "AlignmentReport",
46
+ "ContraryEvidenceResult",
47
+ "DecaySnapshot",
35
48
  "DrawerInfo",
49
+ "MEMORY_SHAPE_KEY",
36
50
  "Memory",
37
51
  "MemoryHit",
52
+ "RelationshipChannelResolution",
53
+ "SHAPE_HALF_LIVES",
38
54
  "SurfaceReport",
39
55
  "TorsionReport",
40
56
  "__version__",
@@ -96,6 +96,8 @@ TORSION_STATUS_THRESHOLD: float = 0.70
96
96
  CONFLICT_STATUS_THRESHOLD: float = 0.40
97
97
  ALIGNED_MIN_SCORE: float = 0.45
98
98
  ALIGNED_MIN_RESONANCE: float = 0.30
99
+ # Per-anchor resonance floor — intent must engage a rule before CONFLICT can block.
100
+ RELEVANCE_MIN_RESONANCE: float = 0.15
99
101
 
100
102
 
101
103
  @dataclass(slots=True)
@@ -482,9 +484,19 @@ def verify_alignment(
482
484
  ]
483
485
  conflicting = [c for c in conflicting if c]
484
486
 
487
+ max_anchor_resonance = max(s.resonance for s in scored) if scored else 0.0
488
+ intent_engages_rule = max_anchor_resonance >= RELEVANCE_MIN_RESONANCE
489
+
485
490
  if torsion >= torsion_threshold:
486
491
  status = "TORSION"
487
492
  explanation = _explain_torsion(text, peak)
493
+ elif not intent_engages_rule and torsion < conflict_threshold:
494
+ status = "ALIGNED"
495
+ explanation = (
496
+ f"Intent does not engage any guard rule "
497
+ f"(max anchor resonance={max_anchor_resonance:.2f}, "
498
+ f"peak torsion={torsion:.2f}). Proceed."
499
+ )
488
500
  elif (
489
501
  torsion >= conflict_threshold
490
502
  or score < ALIGNED_MIN_SCORE