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.
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/PKG-INFO +378 -13
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/README.md +374 -12
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/__init__.py +46 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/ablation.py +7 -6
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/harness.py +3 -4
- pdm_memory-0.2.6/pdm_memory/claims.py +156 -0
- pdm_memory-0.2.6/pdm_memory/connector/__init__.py +10 -0
- pdm_memory-0.2.6/pdm_memory/connector/__main__.py +3 -0
- pdm_memory-0.2.6/pdm_memory/connector/server.py +145 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/math.py +68 -8
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/retrieval.py +27 -35
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/signature.py +63 -3
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/README.md +10 -0
- pdm_memory-0.2.6/pdm_memory/examples/goal_loop_watch_price.py +147 -0
- pdm_memory-0.2.6/pdm_memory/examples/guarded_effects.py +104 -0
- pdm_memory-0.2.6/pdm_memory/examples/guarded_pdm_write.py +125 -0
- pdm_memory-0.2.6/pdm_memory/filters/__init__.py +10 -0
- pdm_memory-0.2.6/pdm_memory/filters/base.py +50 -0
- pdm_memory-0.2.6/pdm_memory/filters/noun_probe.py +35 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/__init__.py +93 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/_json.py +134 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/checker.py +112 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/contract.py +649 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/controller.py +1288 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/executor.py +57 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/guard.py +93 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/job.py +329 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/receipts.py +115 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/states.py +111 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/store.py +367 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/testing.py +203 -0
- pdm_memory-0.2.6/pdm_memory/goal_loop/triggers.py +80 -0
- pdm_memory-0.2.6/pdm_memory/guarded_effects.py +1090 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/batch.py +2 -3
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/ingester.py +17 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/json_transfer.py +18 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/memory.py +760 -372
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/models.py +59 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/__init__.py +94 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/boundary.py +77 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/config.py +58 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/contracts.py +308 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/detector.py +141 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/drift_veto.py +92 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/extraction.py +113 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/invariance.py +113 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/lexicon.py +577 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/perturbation.py +120 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/pipeline.py +222 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/relock.py +69 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/report.py +132 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/service.py +106 -0
- pdm_memory-0.2.6/pdm_memory/noun_probe/verb_coupling.py +147 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/base.py +86 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/cloud_driver.py +88 -6
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/errors.py +5 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/postgres_driver.py +154 -56
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/schema.py +293 -3
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/sqlite_driver.py +162 -15
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/cli.py +10 -12
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/explorer_actions.py +6 -22
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/server.py +1 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/PKG-INFO +378 -13
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/SOURCES.txt +61 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/entry_points.txt +1 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/requires.txt +4 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pyproject.toml +6 -1
- pdm_memory-0.2.6/tests/test_carried.py +63 -0
- pdm_memory-0.2.6/tests/test_claims.py +148 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cli.py +1 -1
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_driver.py +12 -2
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_fields.py +25 -0
- pdm_memory-0.2.6/tests/test_cloud_v19.py +178 -0
- pdm_memory-0.2.6/tests/test_connector.py +222 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_contrary_evidence.py +5 -5
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_correctability.py +14 -17
- pdm_memory-0.2.6/tests/test_count_silent.py +86 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_explorer_console.py +5 -3
- pdm_memory-0.2.6/tests/test_goal_contract.py +440 -0
- pdm_memory-0.2.6/tests/test_goal_loop_controller.py +1337 -0
- pdm_memory-0.2.6/tests/test_goal_loop_store.py +140 -0
- pdm_memory-0.2.6/tests/test_goal_loop_triggers.py +138 -0
- pdm_memory-0.2.6/tests/test_guarded_effects.py +559 -0
- pdm_memory-0.2.6/tests/test_guarded_pdm_write.py +16 -0
- pdm_memory-0.2.6/tests/test_link_store.py +81 -0
- pdm_memory-0.2.6/tests/test_links.py +136 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_math.py +22 -2
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_memory.py +12 -11
- pdm_memory-0.2.6/tests/test_noun_probe_engine.py +645 -0
- pdm_memory-0.2.6/tests/test_noun_probe_filter.py +55 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_pdm_concurrency.py +7 -7
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_pdm_physics.py +4 -32
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_postgres_live.py +10 -0
- pdm_memory-0.2.6/tests/test_retrieve_v19.py +207 -0
- pdm_memory-0.2.6/tests/test_save_filters.py +267 -0
- pdm_memory-0.2.6/tests/test_settlement.py +256 -0
- pdm_memory-0.2.6/tests/test_tag_table.py +98 -0
- pdm_memory-0.2.6/tests/test_three_writers.py +147 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_torsion.py +14 -15
- pdm_memory-0.2.6/tests/test_weight_law.py +75 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/LICENSE +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/auth/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/auth/jwt_handler.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/__main__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/baselines.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/metrics.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench/correctability/scenarios.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/bench.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/alignment.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/constraints.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/core/field_scoped_retrieval.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/event_log.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/field_state_demo.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/guarded_agent_logic.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/handling_contradictions.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/hello_pdm.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/industrial_safety_gate.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/standalone_guard.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/examples/temporal_recall_demo.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/geopass.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/ingest/auto_signature.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/anthropic_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/context_manager.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/gemini_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/groq_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/ollama_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/integrations/openai_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/io/csv_transfer.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_hash.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_store.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/event_sync.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/eventful_postgres.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/eventful_sqlite.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/events.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/factory.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/field_store.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/storage/fields.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/sync.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/__init__.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/bench.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/tools/static/index.html +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory/types.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/dependency_links.txt +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/pdm_memory.egg-info/top_level.txt +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/setup.cfg +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_alignment.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_bench.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_cloud_events.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_constraints.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_current_resolution.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_event_layer_parity.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_evidence_layer_regressions.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_explorer_ui.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_extract_signatures.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_field_memberships.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_field_state.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_gemini_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_geopass.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_groq_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_jwt_auth.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_memory_hooks.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_ollama_adapter.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_postgres_driver.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_projection.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_relationship_state.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_retrieval_diversity.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_review24_followup.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_source_events.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_sqlite_driver.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_storage_factory.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_tier2.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_tier3.py +0 -0
- {pdm_memory-0.2.5 → pdm_memory-0.2.6}/tests/test_trajectory.py +0 -0
- {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.
|
|
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.
|
|
248
|
+
print(h.text, h.pressure, h.action_status)
|
|
245
249
|
|
|
246
|
-
#
|
|
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
|
|
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.
|
|
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
|
-
#
|
|
266
|
-
|
|
267
|
-
|
|
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 #
|
|
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** —
|
|
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)` |
|
|
907
|
-
| `penalize(memory_id, coupling_score)` | Record a wrong prediction:
|
|
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` |
|
|
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 |
|