convmemory 0.4.0__tar.gz → 0.6.0__tar.gz

{convmemory-0.4.0 → convmemory-0.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: convmemory
-Version: 0.4.0
+Version: 0.6.0
 Summary: Lightweight temporal memory reranking for long-term conversational memory.
 Author: ConvMemory contributors
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/pth2002/ConvMemory
 Project-URL: Issues, https://github.com/pth2002/ConvMemory/issues
 Keywords: memory,retrieval,reranking,rag,agents
@@ -25,9 +25,18 @@ Requires-Dist: tqdm>=4.60
 Requires-Dist: scikit-learn>=1.2
 Provides-Extra: hub
 Requires-Dist: huggingface_hub>=0.20; extra == "hub"
+Dynamic: license-file
 
 # ConvMemory
 
+## Technical Report
+
+[ConvMemory: A Lightweight Learned Memory Reranker, a Negative Attribution Result, and a Research-Preview Conflict Editor](paper/convmemory_report.pdf) (May 2026)
+
+**Headline finding**: The temporal-window mechanism originally claimed for ConvMemory is refuted by a 5-seed paired-bootstrap attribution study. The engineering value of the reranker (10-100× cheaper than cross-encoder baselines on conversational memory retrieval) survives the negative attribution.
+
+---
+
 [![CI](https://github.com/pth2002/ConvMemory/actions/workflows/ci.yml/badge.svg)](https://github.com/pth2002/ConvMemory/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
@@ -46,7 +55,7 @@ reranker. Its intended use is recall-oriented memory selection for structured
 memory streams: conversations, user histories, agent traces, task logs, and
 session-level notes.
 
-Current package version: `0.4.0`
+Current package version: `0.6.0`
 
 ## When To Use It
 
@@ -278,6 +287,93 @@ ranked = memory_reranker.retrieve(
 The checkpoint and embeddings must use the same embedding model family and
 embedding dimension.
 
+### ConvMemory v2: Evidence Reranker (recall-preserving top-10 cross-encoder)
+
+ConvMemory v2 is an opt-in evidence reranker that runs after v1. It preserves
+the exact v1 top-10 candidate set, then uses token-level query/memory evidence
+to reorder only that protected prefix. This improves precision and MRR without
+changing v1 Recall@10; if v1 did not retrieve the gold memory into top-10, v2
+cannot rescue it. The v0.5.0 evidence checkpoint is published on Hugging Face,
+but loading remains explicit.
+
+```python
+from convmemory import ConvMemory
+
+model = ConvMemory.from_pretrained("Purdy0228/ConvMemory-LoCoMo-MPNet")
+model.load_evidence_reranker("Purdy0228/ConvMemory-v2-Evidence-Reranker")
+
+ranked = model.retrieve(
+    query=query,
+    memories=candidates,
+    evidence_reranker="v2",
+    top_k=10,
+)
+```
+
+See [Evidence Reranker](docs/EVIDENCE_RERANKER.md) for the v363 headline
+numbers, v364 load-bearing ablations, anti-leak guards, and limitations.
+
+### ConvMemory v3: Validity Context Layer
+
+ConvMemory v3 adds validity evidence for agent memory without changing v1/v2
+ranking by default. In `validity_mode="context"`, returned memories can carry a
+structured `validity` note with possible update evidence; the rank order and
+candidate set are preserved. Automatic demotion is available only as an explicit
+opt-in mode for dense current-state/update workloads.
+
+```python
+model.load_validity_module("Purdy0228/ConvMemory-v3-Validity-Context")
+
+ranked = model.retrieve(
+    query=query,
+    memories=candidates,
+    evidence_reranker="v2",
+    validity_mode="context",
+    top_k=10,
+)
+```
+
+See [Validity Context](docs/VALIDITY_CONTEXT.md) for mode semantics and safety
+contracts. See [V3 Model Card](docs/V3_MODEL_CARD.md) for checkpoint
+provenance, package-level benchmark numbers, latency, and the source-of-truth
+ledger.
+
+### Experimental Memory-MLA Recall Expander
+
+This is **not** the v0.5.0 evidence reranker. See "ConvMemory v2: Evidence
+Reranker" above for the v2 release.
+
+Memory-MLA is an opt-in prefix-protected recall expander. It is not a
+replacement for v1, and it is off by default: `retrieve(query, memories)` remains
+the pure v1 ConvMemory path.
+
+The expander runs after the base ConvMemory ranking. It preserves the top
+`protect_top_k` results exactly, then uses compressed memory latent codes to
+reorder a small suffix window for extra recall. The verified v320 configuration
+is `latent_count=12`, `code_dim=64`, `protect_top_k=7`, and
+`expand_window=16`. It mainly targets Recall@10 / hard-recall improvements; it
+does not claim SOTA.
+
+```python
+from convmemory import ConvMemory
+
+model = ConvMemory.from_pretrained("Purdy0228/ConvMemory-LoCoMo-MPNet")
+model.load_expander("path-or-hub-id-for-memory-mla")
+
+ranked = model.retrieve(
+    query=query,
+    memories=candidates,
+    expander="memory_mla",
+    protect_top_k=7,
+    expand_window=16,
+    top_k=20,
+)
+```
+
+The API is experimental and follows the CCGE-LA opt-in pattern. See
+[Memory-MLA](docs/MEMORY_MLA.md) for mechanism notes, training discipline, and
+the v320 verification numbers.
+
 ## Results
 
 These are retrieval-stage evaluations. They measure whether annotated evidence