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