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.
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/PKG-INFO +177 -17
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/README.md +175 -16
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/__init__.py +20 -4
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/alignment.py +12 -0
- pdm_memory-0.2.5/pdm_memory/core/field_scoped_retrieval.py +180 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/math.py +121 -9
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/retrieval.py +8 -4
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/signature.py +55 -3
- pdm_memory-0.2.5/pdm_memory/event_log.py +904 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/README.md +4 -0
- pdm_memory-0.2.5/pdm_memory/examples/field_state_demo.py +213 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/guarded_agent_logic.py +1 -1
- pdm_memory-0.2.5/pdm_memory/geopass.py +279 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/memory.py +652 -45
- pdm_memory-0.2.5/pdm_memory/models.py +719 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/cloud_driver.py +763 -10
- pdm_memory-0.2.5/pdm_memory/storage/errors.py +50 -0
- pdm_memory-0.2.5/pdm_memory/storage/event_hash.py +347 -0
- pdm_memory-0.2.5/pdm_memory/storage/event_store.py +863 -0
- pdm_memory-0.2.5/pdm_memory/storage/event_sync.py +333 -0
- pdm_memory-0.2.5/pdm_memory/storage/eventful_postgres.py +39 -0
- pdm_memory-0.2.5/pdm_memory/storage/eventful_sqlite.py +99 -0
- pdm_memory-0.2.5/pdm_memory/storage/events.py +991 -0
- pdm_memory-0.2.5/pdm_memory/storage/field_store.py +1053 -0
- pdm_memory-0.2.5/pdm_memory/storage/fields.py +581 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/schema.py +3 -3
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/cli.py +42 -17
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/explorer_actions.py +18 -4
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/server.py +5 -4
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/PKG-INFO +177 -17
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/SOURCES.txt +28 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/requires.txt +1 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pyproject.toml +2 -1
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_alignment.py +21 -1
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_cli.py +6 -1
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_cloud_driver.py +1 -1
- pdm_memory-0.2.5/tests/test_cloud_events.py +292 -0
- pdm_memory-0.2.5/tests/test_cloud_fields.py +558 -0
- pdm_memory-0.2.5/tests/test_contrary_evidence.py +144 -0
- pdm_memory-0.2.5/tests/test_current_resolution.py +120 -0
- pdm_memory-0.2.5/tests/test_event_layer_parity.py +423 -0
- pdm_memory-0.2.5/tests/test_evidence_layer_regressions.py +672 -0
- pdm_memory-0.2.5/tests/test_extract_signatures.py +146 -0
- pdm_memory-0.2.5/tests/test_field_memberships.py +662 -0
- pdm_memory-0.2.5/tests/test_field_state.py +221 -0
- pdm_memory-0.2.5/tests/test_geopass.py +242 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_math.py +106 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_memory.py +137 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_pdm_physics.py +7 -4
- pdm_memory-0.2.5/tests/test_postgres_live.py +220 -0
- pdm_memory-0.2.5/tests/test_projection.py +301 -0
- pdm_memory-0.2.5/tests/test_relationship_state.py +192 -0
- pdm_memory-0.2.5/tests/test_review24_followup.py +339 -0
- pdm_memory-0.2.5/tests/test_source_events.py +772 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_storage_factory.py +1 -1
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_tier2.py +3 -3
- pdm_memory-0.2.5/tests/test_trajectory.py +247 -0
- pdm_memory-0.2.4/pdm_memory/models.py +0 -128
- pdm_memory-0.2.4/pdm_memory/storage/errors.py +0 -26
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/LICENSE +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/auth/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/auth/jwt_handler.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/__main__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/ablation.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/baselines.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/harness.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/metrics.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench/correctability/scenarios.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/bench.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/core/constraints.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/handling_contradictions.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/hello_pdm.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/industrial_safety_gate.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/standalone_guard.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/examples/temporal_recall_demo.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/auto_signature.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/batch.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/ingest/ingester.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/anthropic_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/context_manager.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/gemini_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/groq_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/ollama_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/integrations/openai_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/csv_transfer.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/io/json_transfer.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/base.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/factory.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/postgres_driver.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/storage/sqlite_driver.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/sync.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/__init__.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/bench.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/tools/static/index.html +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory/types.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/dependency_links.txt +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/entry_points.txt +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/pdm_memory.egg-info/top_level.txt +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/setup.cfg +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_bench.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_constraints.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_correctability.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_explorer_console.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_explorer_ui.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_gemini_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_groq_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_jwt_auth.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_memory_hooks.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_ollama_adapter.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_pdm_concurrency.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_postgres_driver.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_retrieval_diversity.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_sqlite_driver.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_tier3.py +0 -0
- {pdm_memory-0.2.4 → pdm_memory-0.2.5}/tests/test_torsion.py +0 -0
- {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.
|
|
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
|
-
|
|
235
|
-
|
|
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
|
-
#
|
|
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 (
|
|
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
|
-
| `
|
|
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** —
|
|
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
|
|
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
|
-
|
|
63
|
-
|
|
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
|
-
#
|
|
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 (
|
|
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
|
-
| `
|
|
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** —
|
|
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
|
|
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="
|
|
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.
|
|
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
|
|
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.
|
|
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
|