pdm-memory 0.2.5__tar.gz → 0.2.6__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 (182) hide show
  1. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/PKG-INFO +378 -13
  2. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/README.md +374 -12
  3. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/__init__.py +46 -1
  4. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/ablation.py +7 -6
  5. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/harness.py +3 -4
  6. pdm_memory-0.2.6/pdm_memory/claims.py +156 -0
  7. pdm_memory-0.2.6/pdm_memory/connector/__init__.py +10 -0
  8. pdm_memory-0.2.6/pdm_memory/connector/__main__.py +3 -0
  9. pdm_memory-0.2.6/pdm_memory/connector/server.py +145 -0
  10. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/math.py +68 -8
  11. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/retrieval.py +27 -35
  12. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/signature.py +63 -3
  13. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/README.md +10 -0
  14. pdm_memory-0.2.6/pdm_memory/examples/goal_loop_watch_price.py +147 -0
  15. pdm_memory-0.2.6/pdm_memory/examples/guarded_effects.py +104 -0
  16. pdm_memory-0.2.6/pdm_memory/examples/guarded_pdm_write.py +125 -0
  17. pdm_memory-0.2.6/pdm_memory/filters/__init__.py +10 -0
  18. pdm_memory-0.2.6/pdm_memory/filters/base.py +50 -0
  19. pdm_memory-0.2.6/pdm_memory/filters/noun_probe.py +35 -0
  20. pdm_memory-0.2.6/pdm_memory/goal_loop/__init__.py +93 -0
  21. pdm_memory-0.2.6/pdm_memory/goal_loop/_json.py +134 -0
  22. pdm_memory-0.2.6/pdm_memory/goal_loop/checker.py +112 -0
  23. pdm_memory-0.2.6/pdm_memory/goal_loop/contract.py +649 -0
  24. pdm_memory-0.2.6/pdm_memory/goal_loop/controller.py +1288 -0
  25. pdm_memory-0.2.6/pdm_memory/goal_loop/executor.py +57 -0
  26. pdm_memory-0.2.6/pdm_memory/goal_loop/guard.py +93 -0
  27. pdm_memory-0.2.6/pdm_memory/goal_loop/job.py +329 -0
  28. pdm_memory-0.2.6/pdm_memory/goal_loop/receipts.py +115 -0
  29. pdm_memory-0.2.6/pdm_memory/goal_loop/states.py +111 -0
  30. pdm_memory-0.2.6/pdm_memory/goal_loop/store.py +367 -0
  31. pdm_memory-0.2.6/pdm_memory/goal_loop/testing.py +203 -0
  32. pdm_memory-0.2.6/pdm_memory/goal_loop/triggers.py +80 -0
  33. pdm_memory-0.2.6/pdm_memory/guarded_effects.py +1090 -0
  34. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/batch.py +2 -3
  35. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/ingester.py +17 -1
  36. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/json_transfer.py +18 -0
  37. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/memory.py +760 -372
  38. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/models.py +59 -0
  39. pdm_memory-0.2.6/pdm_memory/noun_probe/__init__.py +94 -0
  40. pdm_memory-0.2.6/pdm_memory/noun_probe/boundary.py +77 -0
  41. pdm_memory-0.2.6/pdm_memory/noun_probe/config.py +58 -0
  42. pdm_memory-0.2.6/pdm_memory/noun_probe/contracts.py +308 -0
  43. pdm_memory-0.2.6/pdm_memory/noun_probe/detector.py +141 -0
  44. pdm_memory-0.2.6/pdm_memory/noun_probe/drift_veto.py +92 -0
  45. pdm_memory-0.2.6/pdm_memory/noun_probe/extraction.py +113 -0
  46. pdm_memory-0.2.6/pdm_memory/noun_probe/invariance.py +113 -0
  47. pdm_memory-0.2.6/pdm_memory/noun_probe/lexicon.py +577 -0
  48. pdm_memory-0.2.6/pdm_memory/noun_probe/perturbation.py +120 -0
  49. pdm_memory-0.2.6/pdm_memory/noun_probe/pipeline.py +222 -0
  50. pdm_memory-0.2.6/pdm_memory/noun_probe/relock.py +69 -0
  51. pdm_memory-0.2.6/pdm_memory/noun_probe/report.py +132 -0
  52. pdm_memory-0.2.6/pdm_memory/noun_probe/service.py +106 -0
  53. pdm_memory-0.2.6/pdm_memory/noun_probe/verb_coupling.py +147 -0
  54. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/base.py +86 -1
  55. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/cloud_driver.py +88 -6
  56. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/errors.py +5 -1
  57. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/postgres_driver.py +154 -56
  58. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/schema.py +293 -3
  59. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/sqlite_driver.py +162 -15
  60. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/cli.py +10 -12
  61. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/explorer_actions.py +6 -22
  62. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/server.py +1 -1
  63. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/PKG-INFO +378 -13
  64. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/SOURCES.txt +61 -1
  65. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/entry_points.txt +1 -0
  66. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/requires.txt +4 -0
  67. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pyproject.toml +6 -1
  68. pdm_memory-0.2.6/tests/test_carried.py +63 -0
  69. pdm_memory-0.2.6/tests/test_claims.py +148 -0
  70. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cli.py +1 -1
  71. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_driver.py +12 -2
  72. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_fields.py +25 -0
  73. pdm_memory-0.2.6/tests/test_cloud_v19.py +178 -0
  74. pdm_memory-0.2.6/tests/test_connector.py +222 -0
  75. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_contrary_evidence.py +5 -5
  76. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_correctability.py +14 -17
  77. pdm_memory-0.2.6/tests/test_count_silent.py +86 -0
  78. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_explorer_console.py +5 -3
  79. pdm_memory-0.2.6/tests/test_goal_contract.py +440 -0
  80. pdm_memory-0.2.6/tests/test_goal_loop_controller.py +1337 -0
  81. pdm_memory-0.2.6/tests/test_goal_loop_store.py +140 -0
  82. pdm_memory-0.2.6/tests/test_goal_loop_triggers.py +138 -0
  83. pdm_memory-0.2.6/tests/test_guarded_effects.py +559 -0
  84. pdm_memory-0.2.6/tests/test_guarded_pdm_write.py +16 -0
  85. pdm_memory-0.2.6/tests/test_link_store.py +81 -0
  86. pdm_memory-0.2.6/tests/test_links.py +136 -0
  87. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_math.py +22 -2
  88. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_memory.py +12 -11
  89. pdm_memory-0.2.6/tests/test_noun_probe_engine.py +645 -0
  90. pdm_memory-0.2.6/tests/test_noun_probe_filter.py +55 -0
  91. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_pdm_concurrency.py +7 -7
  92. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_pdm_physics.py +4 -32
  93. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_postgres_live.py +10 -0
  94. pdm_memory-0.2.6/tests/test_retrieve_v19.py +207 -0
  95. pdm_memory-0.2.6/tests/test_save_filters.py +267 -0
  96. pdm_memory-0.2.6/tests/test_settlement.py +256 -0
  97. pdm_memory-0.2.6/tests/test_tag_table.py +98 -0
  98. pdm_memory-0.2.6/tests/test_three_writers.py +147 -0
  99. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_torsion.py +14 -15
  100. pdm_memory-0.2.6/tests/test_weight_law.py +75 -0
  101. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/LICENSE +0 -0
  102. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/auth/__init__.py +0 -0
  103. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/auth/jwt_handler.py +0 -0
  104. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/__init__.py +0 -0
  105. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/__main__.py +0 -0
  106. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/__init__.py +0 -0
  107. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/baselines.py +0 -0
  108. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/metrics.py +0 -0
  109. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/scenarios.py +0 -0
  110. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench.py +0 -0
  111. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/__init__.py +0 -0
  112. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/alignment.py +0 -0
  113. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/constraints.py +0 -0
  114. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/field_scoped_retrieval.py +0 -0
  115. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/event_log.py +0 -0
  116. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/__init__.py +0 -0
  117. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/field_state_demo.py +0 -0
  118. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/guarded_agent_logic.py +0 -0
  119. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/handling_contradictions.py +0 -0
  120. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/hello_pdm.py +0 -0
  121. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/industrial_safety_gate.py +0 -0
  122. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/standalone_guard.py +0 -0
  123. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/temporal_recall_demo.py +0 -0
  124. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/geopass.py +0 -0
  125. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/__init__.py +0 -0
  126. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/auto_signature.py +0 -0
  127. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/__init__.py +0 -0
  128. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/anthropic_adapter.py +0 -0
  129. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/context_manager.py +0 -0
  130. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/gemini_adapter.py +0 -0
  131. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/groq_adapter.py +0 -0
  132. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/ollama_adapter.py +0 -0
  133. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/openai_adapter.py +0 -0
  134. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/__init__.py +0 -0
  135. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/csv_transfer.py +0 -0
  136. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/__init__.py +0 -0
  137. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_hash.py +0 -0
  138. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_store.py +0 -0
  139. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_sync.py +0 -0
  140. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/eventful_postgres.py +0 -0
  141. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/eventful_sqlite.py +0 -0
  142. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/events.py +0 -0
  143. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/factory.py +0 -0
  144. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/field_store.py +0 -0
  145. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/fields.py +0 -0
  146. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/sync.py +0 -0
  147. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/__init__.py +0 -0
  148. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/bench.py +0 -0
  149. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/static/index.html +0 -0
  150. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/types.py +0 -0
  151. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/dependency_links.txt +0 -0
  152. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/top_level.txt +0 -0
  153. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/setup.cfg +0 -0
  154. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_alignment.py +0 -0
  155. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_bench.py +0 -0
  156. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_events.py +0 -0
  157. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_constraints.py +0 -0
  158. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_current_resolution.py +0 -0
  159. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_event_layer_parity.py +0 -0
  160. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_evidence_layer_regressions.py +0 -0
  161. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_explorer_ui.py +0 -0
  162. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_extract_signatures.py +0 -0
  163. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_field_memberships.py +0 -0
  164. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_field_state.py +0 -0
  165. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_gemini_adapter.py +0 -0
  166. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_geopass.py +0 -0
  167. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_groq_adapter.py +0 -0
  168. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_jwt_auth.py +0 -0
  169. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_memory_hooks.py +0 -0
  170. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_ollama_adapter.py +0 -0
  171. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_postgres_driver.py +0 -0
  172. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_projection.py +0 -0
  173. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_relationship_state.py +0 -0
  174. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_retrieval_diversity.py +0 -0
  175. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_review24_followup.py +0 -0
  176. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_source_events.py +0 -0
  177. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_sqlite_driver.py +0 -0
  178. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_storage_factory.py +0 -0
  179. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_tier2.py +0 -0
  180. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_tier3.py +0 -0
  181. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_trajectory.py +0 -0
  182. {pdm_memory-0.2.5 → pdm_memory-0.2.6}/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.5
3
+ Version: 0.2.6
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)
@@ -156,6 +156,8 @@ Requires-Dist: fastapi>=0.110; extra == "ui"
156
156
  Requires-Dist: uvicorn[standard]>=0.27; extra == "ui"
157
157
  Provides-Extra: postgres
158
158
  Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
159
+ Provides-Extra: connector
160
+ Requires-Dist: mcp>=1.8; extra == "connector"
159
161
  Provides-Extra: dev
160
162
  Requires-Dist: pytest>=8.0; extra == "dev"
161
163
  Requires-Dist: pytest-cov>=5.0; extra == "dev"
@@ -169,6 +171,7 @@ Requires-Dist: groq>=0.9.0; extra == "dev"
169
171
  Requires-Dist: fastapi>=0.110; extra == "dev"
170
172
  Requires-Dist: uvicorn[standard]>=0.27; extra == "dev"
171
173
  Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
174
+ Requires-Dist: mcp>=1.8; extra == "dev"
172
175
  Dynamic: license-file
173
176
 
174
177
  # PDM — Memory for AI Apps That Works Like Memory
@@ -238,21 +241,26 @@ mem.save("User prefers metric units and short answers", source="manual",
238
241
  shape="behavioral")
239
242
 
240
243
  # Read: resonance retrieval — surfaces what's relevant, not just what matches.
244
+ # Reading writes nothing.
241
245
  hits = mem.recall("how should I format the answer?", k=5)
242
246
 
243
247
  for h in hits:
244
- print(h.text, h.pressure, h.last_reinforced)
248
+ print(h.text, h.pressure, h.action_status)
245
249
 
246
- # Reinforce a memory manually (recall() does this automatically).
250
+ # Use: tell the memory what you acted on. This resets its fade, nothing more.
251
+ mem.touch([hits[0].id])
252
+
253
+ # Grade: when the world answers. reinforce() counts a correct prediction,
254
+ # penalize() a wrong one. Only V moves; P is fixed when a memory is saved.
247
255
  mem.reinforce(hits[0].id)
248
256
 
249
- # Contrary evidence: lower active pressure/V without rewriting the stored fact.
257
+ # Contrary evidence: lower V without rewriting the stored fact.
250
258
  result = mem.apply_contrary_evidence(
251
259
  hits[0].id,
252
260
  "User prefers imperial units",
253
261
  evidence_tags=["units", "formatting", "preferences"],
254
262
  )
255
- print(result.p_before, "→", result.p_after)
263
+ print(result.v_before, "→", result.v_after) # P stays; V falls
256
264
 
257
265
  # Inspect why a memory surfaced.
258
266
  report = mem.explain(hits[0].id, query="how should I format the answer?")
@@ -262,11 +270,85 @@ print(report.render())
262
270
  snap = mem.decay_at(hits[0].id)
263
271
  print(snap.shape, snap.half_life_days, snap.p_effective)
264
272
 
265
- # Store-wide soft-delete of memories below the live P_effective threshold:
266
- counts = mem.decay()
267
- print(f"Decayed: {counts['decayed']}, Deleted: {counts['deleted']}")
273
+ # Nothing is deleted for fading: count the silent memories instead.
274
+ print(mem.count_silent()) # weight under 30 (0.3 of full)
275
+ ```
276
+
277
+ ### Retrieve, use, grade (PDM v1.9)
278
+
279
+ `retrieve()` is `recall()` with everything the call covered. It walks the tag
280
+ index, gates on the carried number (P × V), weighs each candidate at one fixed
281
+ time while its budget lasts, and flags what it returns:
282
+
283
+ ```python
284
+ from datetime import datetime, timedelta, timezone
285
+ from pdm_memory import Claim
286
+
287
+ # Weight = P × V × fade; with no verdicts V = 0.5, so P 80 weighs 40 (gate: 30).
288
+ sensor = mem.save("North flare sensor read 9 bar", tags=["north", "flare", "sensor"],
289
+ p_magnitude=80)
290
+ claim = mem.save(
291
+ "North flare igniter fails by Friday",
292
+ tags=["north", "flare", "igniter"],
293
+ p_magnitude=80,
294
+ rests_on=[sensor], # support: a correction to the sensor re-opens this
295
+ claim=Claim("occurs", datetime.now(timezone.utc) + timedelta(days=4),
296
+ outcome_source="failure-feed"),
297
+ )
298
+
299
+ result = mem.retrieve("north flare", k=5) # min_p=30 by default
300
+ for h in result.hits:
301
+ print(h.text, h.p_effective, h.validation_status, h.context,
302
+ h.support_in_doubt, h.owl, h.duck, h.action_status)
303
+ print(result.routes, result.theta, result.as_of, result.completed)
304
+
305
+ # Ran out of budget? Resume under the same as-of time and order.
306
+ if not result.completed:
307
+ more = mem.retrieve("north flare", continuation=result.continuation)
308
+
309
+ # A search lowers only the weight gate (never under 10 without a named area).
310
+ quiet = mem.search("north flare", min_p_lowered=12)
311
+
312
+ mem.touch([h.id for h in result.hits]) # what you used
313
+ mem.reinforce(sensor) # the sensor was checked: VALIDATED
314
+ mem.penalize(sensor) # later found stuck: a correction, returns the ids it re-opened
315
+ now = datetime.now(timezone.utc)
316
+ mem.report_coverage_gap("failure-feed", now - timedelta(hours=6), now) # a feed that was down
317
+ ```
318
+
319
+ `action_status` is `UNVALIDATED` when the hit stands alone (`STANDALONE`), when
320
+ something it rests on is in doubt, or when it is a safety claim nobody has
321
+ checked (a duck). The memory returns qualified hits; the caller decides.
322
+
323
+ ### Settle claims (PDM v1.9)
324
+
325
+ A claim holds one verdict: `on_time`, `late`, `observed_absent`, `not_by_due`
326
+ or `expired_unobserved`. Amending it moves its one count in V; it never adds a
327
+ second. Run the settlement pass once per cycle; nothing runs it for you.
328
+
329
+ ```python
330
+ # Each cycle: every open claim whose due has come gets its verdict.
331
+ # Bound to a source with nothing reported: not_by_due (graded).
332
+ # Unbound, or a reported gap touches its interval: expired_unobserved (V unchanged).
333
+ report = mem.settle_due_claims()
334
+ print(report.settled, report.reopened, report.failed)
335
+
336
+ # An observation arrives: settle the claim, or amend its verdict while the
337
+ # watch window is open. "occurred", "observed_absent" or "unknown".
338
+ result = mem.validate_claim(claim, "occurred", event_time=now)
339
+ if result: # None when the observation changes nothing
340
+ print(result.verdict, result.reopened) # on_time 0
268
341
  ```
269
342
 
343
+ A wrong verdict on a `VALIDATED` claim is a correction: it re-opens what rests
344
+ on it. A gap reported after the due turns `not_by_due` into
345
+ `expired_unobserved` and restores the count while the watch window is open.
346
+ On a cloud store the server runs the pass, so `settle_due_claims()` raises;
347
+ `validate_claim()` and `report_coverage_gap()` go to the server.
348
+
349
+ `recall(reinforce=True)` and `decay()` still work but are deprecated: the first
350
+ only touches the hits, the second only counts the silent set.
351
+
270
352
  ### Privacy-First Mode
271
353
 
272
354
  Store only SHA-256 hashes of memory text — the content never touches disk:
@@ -275,6 +357,73 @@ Store only SHA-256 hashes of memory text — the content never touches disk:
275
357
  mem = Memory(store="./private.db", user="alice", store_raw=False)
276
358
  ```
277
359
 
360
+ ### Save Filters
361
+
362
+ Opt-in passes every write must clear. A filter has a `name` and a
363
+ `check(text)` that returns a `FilterVerdict`; it sees the text exactly as it
364
+ will be stored (stripped, cut to 500 characters).
365
+
366
+ ```python
367
+ from pdm_memory import FilterRefused, FilterVerdict, Memory
368
+
369
+ class NoSecrets:
370
+ name = "no_secrets"
371
+
372
+ def check(self, text: str) -> FilterVerdict:
373
+ hit = "password" in text.lower()
374
+ return FilterVerdict(self.name, "1", ran=True, passed=not hit,
375
+ terms=("password",) if hit else ())
376
+
377
+ mem = Memory(store="./my_app.db", user="alice", filters=[NoSecrets()])
378
+ # or later: mem.add_filter(NoSecrets())
379
+
380
+ try:
381
+ mem.save("The admin password is hunter2", tags=["admin", "access", "ops"])
382
+ except FilterRefused as err:
383
+ print(err) # no_secrets refused the save: password
384
+ ```
385
+
386
+ - **Refused** (`ran=True, passed=False`): nothing is written and `save` /
387
+ `update(text=...)` raise `FilterRefused` (a `ValueError`). On a cloud store
388
+ no request is sent.
389
+ - **Passed**: the record carries `metadata["filters"][name] = {"version", "ran", "passed", "terms"}`.
390
+ - **Could not read the text** (`ran=False`): the record is written and marked
391
+ with `"ran": False`, so you can find it later.
392
+ - **The filter raises**: the exception reaches you and nothing is written.
393
+ - `save_many` and `ingest` count refused items as `blocked` and write the
394
+ rest; the `blocked` key is there only when filters are set.
395
+ - A dedupe or idempotency hit returns the existing ID before any filter runs.
396
+
397
+ Without `filters`, nothing changes: no calls, no extra metadata, the same
398
+ result dicts.
399
+
400
+ #### Noun Probe filter
401
+
402
+ `NounProbeFilter` runs a Noun Probe AUDIT pass on each fact and refuses one
403
+ that uses a noun against its class (an actor that is only acted upon, a word
404
+ doing another class's job). The method itself is published at
405
+ <https://azus.ai/tools/noun-probe/>.
406
+
407
+ ```python
408
+ from pdm_memory import FilterRefused, Memory, NounProbeFilter
409
+
410
+ mem = Memory(store="./my_app.db", user="alice", filters=[NounProbeFilter()])
411
+
412
+ mem.save("The budget accumulates.", tags=["budget", "planning", "finance"])
413
+
414
+ try:
415
+ mem.save("The operator is deployed and the budget fails.", tags=["ops", "budget", "risk"])
416
+ except FilterRefused as err:
417
+ print(err.verdict.terms) # ('operator',)
418
+ ```
419
+
420
+ - Deterministic: word lists and rules, no model calls, no network.
421
+ - The word lists are English. Text it finds no structure in is written and
422
+ marked as passed.
423
+ - Settings come from the environment: `PDM_NOUN_PROBE_ENABLED` (off → every
424
+ fact is written with `"ran": False`), `PDM_NOUN_PROBE_TOP_N` (12),
425
+ `PDM_NOUN_PROBE_SUBSTITUTES_PER_NOUN` (1).
426
+
278
427
  ---
279
428
 
280
429
  ## ☁️ Ecosystem Mode (AZUS Cloud)
@@ -376,7 +525,8 @@ state = mem.state_at("westfield", datetime(2026, 3, 1, 12, tzinfo=timezone.utc))
376
525
 
377
526
  state.field_memberships # standing in the field, with the intervals it held
378
527
  state.relationships # edges, each with how current its channel reads
379
- state.entities # what this observer may reveal, one keyset page
528
+ state.entities # signatures filed in this field, plus any filed nowhere; what this
529
+ # observer may reveal, one keyset page
380
530
 
381
531
  # Nested fields match by prefix: "westfield" covers "westfield/dqs".
382
532
  state = mem.current_state("westfield/dqs")
@@ -584,7 +734,7 @@ Before an agent **acts**, `verify()` scores the proposed intent against a plain
584
734
 
585
735
  Statuses:
586
736
 
587
- - **ALIGNED** — safe to proceed (`report.is_safe_to_act` is `True`)
737
+ - **ALIGNED** — GAA found no blocking conflict (`report.is_safe_to_act` is `True`); the host still owns permission for the actual operation
588
738
  - **CONFLICT** — soft mismatch / missing anchors (fail-closed by default)
589
739
  - **TORSION** — hard contradiction — block the ACT
590
740
 
@@ -672,6 +822,166 @@ for report in mem.detect_torsion(threshold=0.5):
672
822
 
673
823
  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`.
674
824
 
825
+ ### Boundary Lock guarded effects preview
826
+
827
+ The opt-in `pdm_memory.guarded_effects` module adds a durable action boundary
828
+ around exact structured operations. The owner registers the actual executors and
829
+ current-condition checks. A request stays held until those checks permit it;
830
+ there is no mandatory three- or six-second timer.
831
+
832
+ - Retain full operation, target, parameters, program/policy versions and stable
833
+ action identity. A changed request cannot reuse an existing action identity.
834
+ - Reserve and record dispatch before executing a registered operation. An
835
+ interrupted or uncertain action is not blindly executed again on retry.
836
+ - Save bounded application-state checkpoints and recover a new worker branch
837
+ without erasing decisions, returned results or cumulative limits.
838
+ - Keep this record separate from ordinary memories that may decay or reconcile.
839
+ A returned tool result is not automatically an observed physical outcome.
840
+
841
+ The host must retain the guard and its files outside the worker's authority and
842
+ route protected access through it. This is an application-level action/recovery
843
+ module, not an operating-system sandbox or arbitrary computer-memory rollback.
844
+ Existing `verify()` and `Memory` calls keep their signatures and behavior.
845
+
846
+ See [Boundary Lock Guarded Effects Specification](docs/BOUNDARY_LOCK_GUARDED_EFFECTS_V1.md)
847
+ for the theme, lifecycle and integration responsibilities. The OpenClaw plugin
848
+ also now defaults to blocking when its checker cannot complete; see its
849
+ [configuration and migration notes](plugins/openclaw/README.md).
850
+
851
+ ### Goal Loop preview: the Goal Contract
852
+
853
+ A Goal Loop job is written down once, as one `GoalContract` record that every
854
+ part of the loop reads: what should be true when it is done (`outcome`), the
855
+ measurement that proves it (`proof`), what must never happen (`never`), what to
856
+ protect if possible (`preferences`), what is cheap to give up
857
+ (`sacrifice_order`), what wakes it up (`trigger`), what it may do without asking
858
+ (`autonomy`), how much it may spend (`budget`), who gets told (`notify`) and how
859
+ it can end (`end`).
860
+
861
+ The system may rewrite the plan. It may not rewrite the promise. A contract is
862
+ frozen, and every change goes through `ContractHistory.revise()`, which writes a
863
+ new dated version and keeps the earlier ones on record:
864
+
865
+ - `outcome`, `proof`, `never`, `autonomy`, `budget` and `sacrifice_order` are
866
+ the promise. Changing any of them without an `OwnerApproval` from the
867
+ contract's owner raises `PromiseChangeError`.
868
+ - `preferences`, `trigger`, `notify` and `end` are the plan. Changing them needs
869
+ no approval but still creates a new version.
870
+ - A contract with no named proof source cannot be armed: `ensure_armable()`
871
+ raises `NotArmableError`.
872
+
873
+ ```python
874
+ from datetime import datetime, timezone
875
+
876
+ from pdm_memory.goal_loop import (
877
+ Autonomy, Budget, ContractHistory, GoalContract, OwnerApproval, Trigger, ensure_armable,
878
+ )
879
+
880
+ contract = GoalContract(
881
+ contract_id="watch-mu",
882
+ owner="eric",
883
+ outcome="Eric gets a text when MU crosses $40 from below",
884
+ proof="sms_delivery_receipt",
885
+ never=["Never trade MU shares"],
886
+ trigger=Trigger(kind="threshold", metric="MU.price", direction="rising",
887
+ fire_at="40.00", reset_at="39.50"),
888
+ autonomy=Autonomy(allowed=["sms.send"]),
889
+ budget=Budget(deadline=datetime(2026, 9, 30, tzinfo=timezone.utc)),
890
+ )
891
+ ensure_armable(contract)
892
+
893
+ history = ContractHistory(contract)
894
+ history.revise(outcome="Eric gets a text at $45") # PromiseChangeError
895
+ history.revise(approval=OwnerApproval("eric", "new line"),
896
+ outcome="Eric gets a text at $45") # version 2, version 1 kept
897
+
898
+ saved = history.to_json() # store it anywhere
899
+ history = ContractHistory.from_json(saved)
900
+ ```
901
+
902
+ No PDM store, account or network is needed. Prices and costs are `Decimal` and
903
+ are serialized as text; every datetime must be timezone-aware. Owner approval
904
+ is cooperative: the SDK checks that the approval names the contract's owner,
905
+ and the host decides whether a person really gave it.
906
+
907
+ ### Goal Loop preview: the controller
908
+
909
+ `GoalLoopController` carries one contract from `drafted` to a final state:
910
+
911
+ ```
912
+ drafted -> approved -> armed -> waiting -> triggered -> guard_checked
913
+ -> acting -> verifying -> complete
914
+ ```
915
+
916
+ with side paths `retrying`, `escalated`, `paused`, `out_of_budget`, `conflict`,
917
+ `cancelled`, `impossible` and `stopped`. It has no threads and no timers. Your host hands it readings
918
+ with `observe()` and calls `tick()` now and then; between those calls nothing
919
+ runs and nothing is spent.
920
+
921
+ - **One crossing, one action.** A threshold trigger fires when the value crosses
922
+ `fire_at` and re-arms only after it drops below `reset_at` (the first reading
923
+ never fires). Each firing has a fixed `action_id`, which is also the
924
+ executor's idempotency key, and a repeated `observation_id` is ignored.
925
+ - **Guard before every step.** `DefaultGuard` denies any operation not listed in
926
+ `autonomy.allowed`, then runs `verify()` against `never`. Pass only rules
927
+ that forbid things; limits the controller enforces itself belong in the
928
+ trigger and budget. A guard that raises is a failed check: the step does not
929
+ run and is checked again on the next try.
930
+ - **A checker proves the result.** An executor's return is not proof. The job
931
+ reaches `complete` only when the checker returns a `ProofReceipt` from the
932
+ contract's proof source; `PROVEN` without one is recorded and ignored.
933
+ - **Honest endings.** Budget (`max_actions`, `max_attempts`, `max_cost`) ends a
934
+ job in `out_of_budget` with the reason; by default an action gets one retry.
935
+ The `deadline` ends the watch period: nothing new fires, a step already fired
936
+ still gets its retry and proof, and the job ends `complete` only if every
937
+ action was proved, `stopped` otherwise. A step that may have run is never
938
+ repeated on its own: the job escalates, and the owner settles it with
939
+ `submit_evidence()` (it did arrive) or `resolve(..., "retry")`. A question
940
+ nobody answers within `confirm_expiry` (7 days) stops the job as unconfirmed.
941
+ - **Pause.** `pause()` suspends a job between steps; `resume()` checks its
942
+ grounds again and never fires a crossing that happened during the pause.
943
+ - **Every move leaves a receipt**, chained by hash; `verify_receipts()` checks it.
944
+
945
+ ```python
946
+ from pdm_memory.goal_loop import (
947
+ ActionResult, CallableChecker, GoalLoopController, Observation, OwnerApproval,
948
+ ProofReceipt, ProofVerdict, SqliteJobStore, StepTemplate,
949
+ )
950
+
951
+ def send_sms(step, *, idempotency_key): # your hands
952
+ ...
953
+ return ActionResult(reference="msg-1")
954
+
955
+ def delivered(contract, step, result, evidence, now): # your proof of the result
956
+ return ProofVerdict("PROVEN", "delivered",
957
+ ProofReceipt("sms_delivery_receipt", "dlr-1", now))
958
+
959
+ controller = GoalLoopController(
960
+ store=SqliteJobStore("jobs.db"), # omit for an in-memory store
961
+ checkers={"sms_delivery_receipt": CallableChecker("sms_delivery_receipt", delivered)},
962
+ executors={"sms.send": send_sms},
963
+ )
964
+ job_id = controller.create(history, step=StepTemplate("sms.send", "+15550100",
965
+ "Send SMS to owner: {metric} crossed {fire_at}"))
966
+ controller.approve(job_id, OwnerApproval("eric"))
967
+ controller.arm(job_id) # needs a proof source and a checker
968
+ controller.observe(job_id, Observation(observation_id="t1", observed_at=now,
969
+ metric="MU.price", value="40.12"))
970
+ controller.tick() # retries, deadlines, stuck steps
971
+ ```
972
+
973
+ Run `python -m pdm_memory.examples.goal_loop_watch_price` for the full MU
974
+ example. Backends implement `JobStore`; check yours with
975
+ `pdm_memory.goal_loop.testing.run_job_store_contract`. See
976
+ [Goal Loop v1](docs/GOAL_LOOP_V1.md) for the state table, escalation kinds and
977
+ the store contract.
978
+
979
+ The controller is cooperative, like the Boundary Lock preview: it cannot stop an
980
+ executor that bypasses it or a caller that edits the store, and the guard,
981
+ checker and executor run on your thread. Version 1 runs one action at a time per
982
+ job; an event that arrives mid-action is recorded as `fire_suppressed_busy` for
983
+ the host to replay.
984
+
675
985
  ---
676
986
 
677
987
  ## 📥 Data Ingestion
@@ -875,6 +1185,38 @@ Opens `http://localhost:8080` with a D3 force graph:
875
1185
 
876
1186
  API endpoints used by the UI: `GET /api/v1/memory-map`, `GET /api/v1/torsion`.
877
1187
 
1188
+ ### Use it as a connector (Claude and other MCP assistants)
1189
+
1190
+ The connector gives your PDM to the chat assistant you already use, with no code. The assistant recalls before it answers and saves what lands.
1191
+
1192
+ ```bash
1193
+ pip install "pdm-memory[connector]"
1194
+ ```
1195
+
1196
+ Add it to a desktop app that speaks MCP (for example, the `mcpServers` section of Claude Desktop's config):
1197
+
1198
+ ```json
1199
+ {
1200
+ "mcpServers": {
1201
+ "pdm": {
1202
+ "command": "pdm-memory-connector",
1203
+ "env": { "PDM_STORE": "/path/to/my_pdm.db", "PDM_USER": "me" }
1204
+ }
1205
+ }
1206
+ }
1207
+ ```
1208
+
1209
+ For the cloud store use `"PDM_STORE": "cloud"` and add `"PDM_TOKEN"`. The token lives only in this config on your machine and never passes through a chat.
1210
+
1211
+ Four tools:
1212
+
1213
+ - `pdm_recall` — the memories that resonate with a query. A lookup is not a use: recall through the connector does not reinforce the memories it returns.
1214
+ - `pdm_save` — one durable memory, with a drawer, tags and a pressure. Saved memories carry the source label `connector` (`PDM_CONNECTOR_SOURCE` to change it).
1215
+ - `pdm_drawers` — the drawers with their counts and average pressure.
1216
+ - `pdm_explain` — why one memory holds the pressure it holds.
1217
+
1218
+ It runs over stdio by default. `PDM_CONNECTOR_TRANSPORT=streamable-http` serves it at `http://127.0.0.1:8000/mcp` instead, on this machine only. `python -m pdm_memory.connector` works too. If it can't start (no `PDM_STORE`, a wrong path, no token for the cloud store), it says why on stderr and exits.
1219
+
878
1220
  ---
879
1221
 
880
1222
  ## 📖 API Reference
@@ -892,6 +1234,29 @@ Store-free Goal-Anchor Alignment. Pass a proposed action and one or more rule st
892
1234
 
893
1235
  Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before triggering ACT.
894
1236
 
1237
+ ### `GoalContract`, `ContractHistory` and `GoalLoopController` (preview)
1238
+
1239
+ Store-free record of one Goal Loop job. See [Goal Loop preview](#goal-loop-preview-the-goal-contract) and [the controller](#goal-loop-preview-the-controller).
1240
+
1241
+ | Name | Description |
1242
+ |------|-------------|
1243
+ | `GoalContract(contract_id, owner, outcome, trigger, proof, never, preferences, sacrifice_order, autonomy, budget, notify, end)` | Frozen record; `proof` may be a `Proof` or a source name |
1244
+ | `ContractHistory(first)` | All versions of one contract, starting at version 1 |
1245
+ | `history.revise(*, approval=None, reason="", now=None, **changes)` → `GoalContract` | Writes version N+1; promise changes need `OwnerApproval` from the owner |
1246
+ | `history.current`, `history.versions()`, `history.version(n)` | Read versions; earlier versions never change |
1247
+ | `history.to_json()` / `ContractHistory.from_json(text)` | Canonical JSON; loading checks the version chain and approvals |
1248
+ | `ensure_armable(contract)` | Raises `NotArmableError` when no proof source is named |
1249
+ | `PROMISE_FIELDS` | `outcome`, `proof`, `never`, `autonomy`, `budget`, `sacrifice_order` |
1250
+ | `GoalLoopController(*, checkers, executors, store=None, guard=None, clock, retry_base, retry_cap, proof_timeout, action_timeout, confirm_expiry, default_max_attempts)` | Moves jobs through their states |
1251
+ | `create(history, *, step)` → job id; `approve`, `arm` | `drafted` to `approved` to `waiting` |
1252
+ | `observe(job_id, Observation)` → `Job` | A reading or event; fires at most once per crossing |
1253
+ | `tick(now=None)` → `list[Job]` | Retries, deadlines, lost steps, proof timeouts |
1254
+ | `submit_evidence(job_id, action_id, evidence)` | Proof from outside; also settles an escalated step |
1255
+ | `resolve(job_id, approval, *, decision)` | Owner answers an escalation: `proceed`, `skip` or `retry` |
1256
+ | `revise_contract(job_id, *, approval=None, **changes)` | New contract version while no step is in flight |
1257
+ | `pause(job_id, reason)`, `resume(job_id, reason="")` | Suspend between steps; resume after checking the grounds again |
1258
+ | `cancel(job_id, reason)`, `job()`, `receipts()`, `verify_receipts()` | Stop, read back, check the chain |
1259
+
895
1260
  ### `Memory(store, *, user, token, refresh_token, cloud_url, store_raw)`
896
1261
 
897
1262
  `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.
@@ -903,12 +1268,12 @@ Use `report.is_safe_to_act` (True only when `status == "ALIGNED"`) before trigge
903
1268
  | `recall(query, k, min_pressure, search_cost, drawer, reinforce)` → `List[MemoryHit]` | Retrieve top-k relevant memories |
904
1269
  | `verify_alignment(intent_text, min_pressure, k_goals, torsion_threshold)` → `AlignmentReport` | Same GAA gate against goals already stored in Memory |
905
1270
  | `detect_torsion(drawer, threshold)` → `List[TorsionReport]` | Find contradicting facts (Reverse Resonance) |
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 |
1271
+ | `reinforce(memory_id, coupling_score)` | Record a correct prediction: V rises, the memory becomes `VALIDATED`; P does not move |
1272
+ | `penalize(memory_id, coupling_score)` → `set[str]` | Record a wrong prediction: V falls; P does not move. On a `VALIDATED` memory it is a correction and returns the ids it re-opened |
908
1273
  | `apply_contrary_evidence(target, evidence, …)` → `ContraryEvidenceResult` | Immediate V-miss + Δp on conflicting evidence; does not rewrite historical fact fields |
909
1274
  | `delete(memory_id)` → `bool` | Soft-delete when storage supports it |
910
1275
  | `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 |
1276
+ | `decay(dry_run=False)` → `dict` | Deprecated: deletes nothing, only counts the silent set; call `count_silent()` |
912
1277
  | `explain(memory_id, query)` → `ExplainReport` | Show why a memory has its current pressure |
913
1278
  | `list(limit, min_pressure, drawer, cursor_id)` → `MemoryListPage` | Keyset page of memories (storage list API on cloud) |
914
1279
  | `sync(direction, token, cloud_url)` → `SyncReport` | Sync local ↔ cloud |