voltmem 0.2.0__tar.gz → 0.2.1__tar.gz

{voltmem-0.2.0 → voltmem-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voltmem
-Version: 0.2.0
+Version: 0.2.1
 Summary: Current-truth memory for LLM agents — protect stable facts, update volatile ones.
 Author: VoltMem contributors
 License-Expression: MIT
@@ -31,7 +31,7 @@ Dynamic: license-file
 
 # VoltMem
 
-[![PyPI](https://img.shields.io/pypi/v/voltmem)](https://pypi.org/project/voltmem/)
+[![Version](https://img.shields.io/badge/version-0.2.1-blue)](https://pypi.org/project/voltmem/)
 [![Python](https://img.shields.io/pypi/pyversions/voltmem)](https://pypi.org/project/voltmem/)
 [![License: MIT](https://img.shields.io/pypi/l/voltmem)](https://github.com/Rouche01/voltmem/blob/main/LICENSE)
 
@@ -47,7 +47,7 @@ volatile memories rank lower at search time.
 
 > Mem0 remembers relevant facts. VoltMem remembers **current truth**.
 
-**Research & benchmarks:** [docs/RESEARCH.md](docs/RESEARCH.md)
+**Research & benchmarks:** [docs/RESEARCH.md](docs/RESEARCH.md) · **Known limits & roadmap:** [docs/OPEN_PROBLEMS.md](docs/OPEN_PROBLEMS.md)
 
 ---
 
@@ -133,6 +133,7 @@ flowchart LR
 | User moves cities | Berlin and Paris both stored | **Updates** to current city |
 | Old project name in haystack | Ranks by similarity | **Down-ranks** stale volatile facts |
 | Confident wrong blip on stable pref | Often accepted | **Resists** corruption |
+| Career / role change (medium-stable) | Often blocked or duplicated | **Updates** on strong explicit contradiction |
 
 ### Example results (reproducible)
 
@@ -168,6 +169,15 @@ Run locally with `pip install -e ".[embeddings]"`. Embeddings:
 **VoltMem clearer wins: 3/3.** Mem0 keeps contradictory facts; VoltMem updates volatile
 slots and protects stable prefs via domain volatility + slot-aware linking.
 
+**`experiments/voltmem_eval.py`** — end-to-end escalation + retrieval (real vs flat vs swap):
+
+| Battery | real profile | flat (equal V) | swap (inverted V) |
+|---|---|---|---|
+| A — selective updating | **20/20** | 15/20 | 7/20 |
+| B — retrieval separation | **+0.589** | +0.202 | −0.267 |
+
+Includes the `professional_context` career-change probe (strong explicit evidence → update).
+
 **`experiments/memory_demo.py`** — 3 final Q&A checks vs ground truth:
 
 | Policy | Score |
@@ -185,6 +195,7 @@ facts and **tracks weak-but-true updates** on volatile ones. Full distributions:
 python examples/contradiction_demo.py
 python experiments/mem0_comparison.py
 python experiments/mem0_side_by_side.py   # pip install mem0ai; OPENAI_API_KEY or MEM0_BACKEND=ollama
+python experiments/voltmem_eval.py        # 20/20 escalation probes + retrieval separation
 python experiments/memory_demo.py
 ```
 
@@ -225,9 +236,24 @@ bob   = create_memory("app.db", user_id="bob")
 | `examples/contradiction_demo.py` | VoltMem vs always-add on contradictions |
 | `experiments/mem0_comparison.py` | 3-scenario head-to-head vs always-add |
 | `experiments/mem0_side_by_side.py` | 3-scenario head-to-head vs real Mem0 (3/3 wedge) |
+| `experiments/voltmem_eval.py` | End-to-end escalation + retrieval (20/20 probes, real > flat > swap) |
+| `experiments/calibrate_escalation.py` | Print E_t vs θ table for tuning explicit-override constants |
 | `examples/quickstart_batteries.py` | `remember()` / `recall()` low-level API |
 | `examples/multi_tenant.py` | One DB, many users |
 | `examples/langchain_agent.py` | LangChain adapter |
+| `examples/chat_app/` | Memory-aware CLI chat (extendable to web UI) |
+| `examples/custom_classifier.py` | Pluggable ``KeywordClassifier`` + ``DomainRegistry`` |
+
+### Chat app (CLI)
+
+```bash
+pip install -e ".[embeddings]"
+python -m examples.chat_app              # REPL; uses Ollama if running, else echo mode
+python -m examples.chat_app --demo       # scripted smoke test
+python -m examples.chat_app --show-recall
+```
+
+Slash commands: `/memories`, `/search <query>`, `/clear`, `/reset`, `/help`.
 
 ---
 
@@ -238,11 +264,41 @@ bob   = create_memory("app.db", user_id="bob")
 | `personality_trait` | 0.05 | Very protected |
 | `core_preference` | 0.08 | Very protected |
 | `biographical` | 0.10 | High protection |
+| `professional_context` | 0.30 | Medium — job/role (career changes) |
+| `location` | 0.60 | Updates readily (Berlin → Paris) |
 | `current_project` | 0.55 | Updates readily |
 | `emotional_context` | 0.80 | Fast-moving |
 | `current_task` | 0.90 | Minimal protection |
 
-Custom domains: `voltmem/domains.py`.
+Custom domains: register via ``DomainRegistry`` and pass to ``create_memory(domains=...)``.
+Pluggable classifiers: ``create_memory(classifier=...)`` — ``"heuristic"``, ``"llm"``, ``KeywordClassifier``, or a callable dict.
+
+Optional: ``create_memory(..., auto_discover=True)`` learns per-domain volatility from
+confirm / mismatch / supersede patterns (blended with priors above; cold-start applies).
+
+```python
+from voltmem import create_memory, DomainRegistry, KeywordClassifier, ChainedClassifier, HeuristicClassifier
+
+domains = DomainRegistry()
+domains.register("style_preference", 0.08)
+domains.register("style_constraint", 0.25)
+
+mem = create_memory(
+    "app.db",
+    user_id="alice",
+    domains=domains,
+    classifier=ChainedClassifier([
+        KeywordClassifier({
+            "style_preference": ["prefer", "darker colors", "minimal"],
+            "style_constraint": ["no wool", "tight budget"],
+        }),
+        HeuristicClassifier(),
+    ]),
+)
+
+mem.add("I prefer darker colors and minimal fits")
+hits = mem.search("what colors does the user like?")
+```
 
 ---
 
@@ -255,6 +311,7 @@ python tests/test_client.py
 ```
 
 Experiments and benchmarks live in `experiments/` — see [docs/RESEARCH.md](docs/RESEARCH.md).
+Open problems and roadmap: [docs/OPEN_PROBLEMS.md](docs/OPEN_PROBLEMS.md).
 
 ---
 

{voltmem-0.2.0 → voltmem-0.2.1}/README.md

@@ -1,6 +1,6 @@
 # VoltMem
 
-[![PyPI](https://img.shields.io/pypi/v/voltmem)](https://pypi.org/project/voltmem/)
+[![Version](https://img.shields.io/badge/version-0.2.1-blue)](https://pypi.org/project/voltmem/)
 [![Python](https://img.shields.io/pypi/pyversions/voltmem)](https://pypi.org/project/voltmem/)
 [![License: MIT](https://img.shields.io/pypi/l/voltmem)](https://github.com/Rouche01/voltmem/blob/main/LICENSE)
 
@@ -16,7 +16,7 @@ volatile memories rank lower at search time.
 
 > Mem0 remembers relevant facts. VoltMem remembers **current truth**.
 
-**Research & benchmarks:** [docs/RESEARCH.md](docs/RESEARCH.md)
+**Research & benchmarks:** [docs/RESEARCH.md](docs/RESEARCH.md) · **Known limits & roadmap:** [docs/OPEN_PROBLEMS.md](docs/OPEN_PROBLEMS.md)
 
 ---
 
@@ -102,6 +102,7 @@ flowchart LR
 | User moves cities | Berlin and Paris both stored | **Updates** to current city |
 | Old project name in haystack | Ranks by similarity | **Down-ranks** stale volatile facts |
 | Confident wrong blip on stable pref | Often accepted | **Resists** corruption |
+| Career / role change (medium-stable) | Often blocked or duplicated | **Updates** on strong explicit contradiction |
 
 ### Example results (reproducible)
 
@@ -137,6 +138,15 @@ Run locally with `pip install -e ".[embeddings]"`. Embeddings:
 **VoltMem clearer wins: 3/3.** Mem0 keeps contradictory facts; VoltMem updates volatile
 slots and protects stable prefs via domain volatility + slot-aware linking.
 
+**`experiments/voltmem_eval.py`** — end-to-end escalation + retrieval (real vs flat vs swap):
+
+| Battery | real profile | flat (equal V) | swap (inverted V) |
+|---|---|---|---|
+| A — selective updating | **20/20** | 15/20 | 7/20 |
+| B — retrieval separation | **+0.589** | +0.202 | −0.267 |
+
+Includes the `professional_context` career-change probe (strong explicit evidence → update).
+
 **`experiments/memory_demo.py`** — 3 final Q&A checks vs ground truth:
 
 | Policy | Score |
@@ -154,6 +164,7 @@ facts and **tracks weak-but-true updates** on volatile ones. Full distributions:
 python examples/contradiction_demo.py
 python experiments/mem0_comparison.py
 python experiments/mem0_side_by_side.py   # pip install mem0ai; OPENAI_API_KEY or MEM0_BACKEND=ollama
+python experiments/voltmem_eval.py        # 20/20 escalation probes + retrieval separation
 python experiments/memory_demo.py
 ```
 
@@ -194,9 +205,24 @@ bob   = create_memory("app.db", user_id="bob")
 | `examples/contradiction_demo.py` | VoltMem vs always-add on contradictions |
 | `experiments/mem0_comparison.py` | 3-scenario head-to-head vs always-add |
 | `experiments/mem0_side_by_side.py` | 3-scenario head-to-head vs real Mem0 (3/3 wedge) |
+| `experiments/voltmem_eval.py` | End-to-end escalation + retrieval (20/20 probes, real > flat > swap) |
+| `experiments/calibrate_escalation.py` | Print E_t vs θ table for tuning explicit-override constants |
 | `examples/quickstart_batteries.py` | `remember()` / `recall()` low-level API |
 | `examples/multi_tenant.py` | One DB, many users |
 | `examples/langchain_agent.py` | LangChain adapter |
+| `examples/chat_app/` | Memory-aware CLI chat (extendable to web UI) |
+| `examples/custom_classifier.py` | Pluggable ``KeywordClassifier`` + ``DomainRegistry`` |
+
+### Chat app (CLI)
+
+```bash
+pip install -e ".[embeddings]"
+python -m examples.chat_app              # REPL; uses Ollama if running, else echo mode
+python -m examples.chat_app --demo       # scripted smoke test
+python -m examples.chat_app --show-recall
+```
+
+Slash commands: `/memories`, `/search <query>`, `/clear`, `/reset`, `/help`.
 
 ---
 
@@ -207,11 +233,41 @@ bob   = create_memory("app.db", user_id="bob")
 | `personality_trait` | 0.05 | Very protected |
 | `core_preference` | 0.08 | Very protected |
 | `biographical` | 0.10 | High protection |
+| `professional_context` | 0.30 | Medium — job/role (career changes) |
+| `location` | 0.60 | Updates readily (Berlin → Paris) |
 | `current_project` | 0.55 | Updates readily |
 | `emotional_context` | 0.80 | Fast-moving |
 | `current_task` | 0.90 | Minimal protection |
 
-Custom domains: `voltmem/domains.py`.
+Custom domains: register via ``DomainRegistry`` and pass to ``create_memory(domains=...)``.
+Pluggable classifiers: ``create_memory(classifier=...)`` — ``"heuristic"``, ``"llm"``, ``KeywordClassifier``, or a callable dict.
+
+Optional: ``create_memory(..., auto_discover=True)`` learns per-domain volatility from
+confirm / mismatch / supersede patterns (blended with priors above; cold-start applies).
+
+```python
+from voltmem import create_memory, DomainRegistry, KeywordClassifier, ChainedClassifier, HeuristicClassifier
+
+domains = DomainRegistry()
+domains.register("style_preference", 0.08)
+domains.register("style_constraint", 0.25)
+
+mem = create_memory(
+    "app.db",
+    user_id="alice",
+    domains=domains,
+    classifier=ChainedClassifier([
+        KeywordClassifier({
+            "style_preference": ["prefer", "darker colors", "minimal"],
+            "style_constraint": ["no wool", "tight budget"],
+        }),
+        HeuristicClassifier(),
+    ]),
+)
+
+mem.add("I prefer darker colors and minimal fits")
+hits = mem.search("what colors does the user like?")
+```
 
 ---
 
@@ -224,6 +280,7 @@ python tests/test_client.py
 ```
 
 Experiments and benchmarks live in `experiments/` — see [docs/RESEARCH.md](docs/RESEARCH.md).
+Open problems and roadmap: [docs/OPEN_PROBLEMS.md](docs/OPEN_PROBLEMS.md).
 
 ---
 

{voltmem-0.2.0 → voltmem-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "voltmem"
-version = "0.2.0"
+version = "0.2.1"
 description = "Current-truth memory for LLM agents — protect stable facts, update volatile ones."
 readme = "README.md"
 license = "MIT"

voltmem-0.2.1/tests/test_classifiers.py

@@ -0,0 +1,128 @@
+"""Tests for pluggable classifiers and DomainRegistry."""
+
+import os
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from voltmem import (  # noqa: E402
+    ChainedClassifier,
+    DomainRegistry,
+    HeuristicClassifier,
+    KeywordClassifier,
+    create_memory,
+)
+from voltmem import domains as dom  # noqa: E402
+
+
+def test_keyword_classifier_matches_custom_domain():
+    domains = DomainRegistry()
+    domains.register("style_preference", 0.08)
+    restore = domains.install()
+    try:
+        clf = KeywordClassifier({
+            "style_preference": ["darker colors", "minimal style"],
+        })
+        assert clf.classify_domain("I prefer darker colors") == "style_preference"
+        assert clf.match_domain("hello there") is None
+    finally:
+        restore()
+
+
+def test_chained_classifier_falls_through_to_heuristic():
+    domains = DomainRegistry()
+    domains.register("style_constraint", 0.25)
+    restore = domains.install()
+    try:
+        clf = ChainedClassifier([
+            KeywordClassifier({"style_constraint": ["no wool", "tight budget"]}),
+            HeuristicClassifier(),
+        ])
+        assert clf.classify_domain("no wool please") == "style_constraint"
+        assert clf.classify_domain("I live in Berlin") == "location"
+    finally:
+        restore()
+
+
+def test_callable_classifier_dict():
+    with create_memory(
+        ":memory:",
+        user_id="u1",
+        embeddings=False,
+        classifier={
+            "classify": lambda t: "custom_domain"
+            if "stylens" in t.lower() else "stated_preference",
+            "mismatch": lambda n, e, s: 0.05 if s > 0.8 else 0.7,
+        },
+        domains=DomainRegistry().register("custom_domain", 0.4),
+    ) as mem:
+        row = mem.add("stylens user prefers navy")
+        assert row["domain"] == "custom_domain"
+
+
+def test_create_memory_classifier_string_llm_alias():
+    # Should not raise — builds LLM classifier (may fall back on classify)
+    with create_memory(
+        ":memory:",
+        classifier="llm",
+        embeddings=False,
+    ) as mem:
+        assert mem.layer._extractor is not None
+
+
+def test_domain_registry_restored_on_close():
+    before = dict(dom.DOMAIN_VOLATILITY)
+    reg = DomainRegistry().register("ephemeral_domain", 0.33, slot=True)
+    with create_memory(":memory:", domains=reg, embeddings=False) as mem:
+        assert "ephemeral_domain" in dom.DOMAIN_VOLATILITY
+        assert "ephemeral_domain" in dom.SLOT_DOMAINS
+        mem.add("ephemeral fact", extract=False)
+    assert dom.DOMAIN_VOLATILITY == before
+    assert "ephemeral_domain" not in dom.SLOT_DOMAINS
+
+
+def test_domain_registry_custom_domain_classified():
+    domains = DomainRegistry()
+    domains.register("style_preference", 0.08)
+    classifier = KeywordClassifier({
+        "style_preference": ["darker colors", "minimal style"],
+    })
+    with create_memory(
+        ":memory:",
+        domains=domains,
+        classifier=classifier,
+        embeddings=False,
+    ) as mem:
+        row = mem.add("I love minimal style and darker colors")
+        assert row["domain"] == "style_preference"
+        assert "style_preference" in domains.known_domains()
+
+
+def test_legacy_extractor_kwarg_still_works():
+    custom = HeuristicClassifier(relate_similarity=0.6)
+    with create_memory(":memory:", extractor=custom, embeddings=False) as mem:
+        assert mem.layer._extractor is custom
+
+
+if __name__ == "__main__":
+    tests = [
+        test_keyword_classifier_matches_custom_domain,
+        test_chained_classifier_falls_through_to_heuristic,
+        test_callable_classifier_dict,
+        test_create_memory_classifier_string_llm_alias,
+        test_domain_registry_restored_on_close,
+        test_domain_registry_custom_domain_classified,
+        test_legacy_extractor_kwarg_still_works,
+    ]
+    failed = 0
+    for t in tests:
+        try:
+            t()
+            print(f"  PASS  {t.__name__}")
+        except Exception as exc:
+            failed += 1
+            print(f"  FAIL  {t.__name__}: {exc}")
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    raise SystemExit(1 if failed else 0)

voltmem-0.2.1/tests/test_discovery.py

@@ -0,0 +1,142 @@
+"""Tests for domain auto-discovery (Tier 1)."""
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from voltmem import (  # noqa: E402
+    MemoryLayer,
+    DomainStats,
+    VolatilityTracker,
+    blend_volatility,
+    update_volatility_ema,
+    VOL_DRIFT_MAX,
+    DOMAIN_VOLATILITY,
+)
+from voltmem.domains import MemoryItem  # noqa: E402
+from voltmem.scoring import should_escalate  # noqa: E402
+
+
+def test_domain_stats_empirical_volatility_rises_with_supersedes():
+    stats = DomainStats(domain="location")
+    for _ in range(5):
+        stats.record("audited", mismatch=0.8)
+    assert stats.empirical_volatility > 0.4
+
+
+def test_blend_volatility_requires_min_observations():
+    prior = 0.08
+    assert blend_volatility(prior, 0.9, n_observations=1) == prior
+    blended = blend_volatility(prior, 0.9, n_observations=10)
+    assert blended > prior
+
+
+def test_prior_anchored_ema_clamps_drift():
+    item = MemoryItem(
+        id="x",
+        content="pref",
+        domain="personality_trait",
+        source="weak_inference",
+        volatility_ema=-1.0,
+        created_at=0.0,
+        last_confirmed_at=0.0,
+    )
+    prior = DOMAIN_VOLATILITY["personality_trait"]
+    updated = update_volatility_ema(item, observed_mismatch=0.9, source="weak_inference")
+    assert updated <= prior + VOL_DRIFT_MAX + 1e-9
+    assert updated >= prior - VOL_DRIFT_MAX - 1e-9
+
+
+def test_auto_discover_records_observations():
+    with MemoryLayer(":memory:", auto_discover=True) as mem:
+        mem.write("I live in Berlin", domain="location")
+        mem.observe(
+            "I moved to Paris",
+            domain="location",
+            mismatch_magnitude=0.85,
+            source="explicit_statement",
+        )
+        summary = mem.summary()
+        assert summary["auto_discover"] is True
+        loc = summary["domain_discovery"]["location"]
+        assert loc["n_supersedes"] >= 1
+        assert loc["empirical"] > 0.0
+
+
+def test_auto_discover_persists_across_sessions():
+    with tempfile.TemporaryDirectory() as tmp:
+        db = os.path.join(tmp, "discover.db")
+        with MemoryLayer(db, namespace="alice", auto_discover=True) as mem:
+            mem.write("I prefer concise answers", domain="core_preference")
+            for _ in range(4):
+                mem.observe(
+                    "I prefer concise answers",
+                    domain="core_preference",
+                    mismatch_magnitude=0.05,
+                    source="explicit_statement",
+                )
+        with MemoryLayer(db, namespace="alice", auto_discover=True) as mem2:
+            stats = mem2.summary()["domain_discovery"]["core_preference"]
+            assert stats["n_confirms"] >= 4
+
+
+def test_auto_discover_off_by_default():
+    with MemoryLayer(":memory:") as mem:
+        assert mem.auto_discover is False
+        assert mem._tracker is None
+        mem.write("I live in Berlin", domain="location")
+        summary = mem.summary()
+        assert summary["domain_discovery"] == {}
+
+
+def test_weak_inference_does_not_supersede_stable_with_auto_discover():
+    """Repeated weak contradictions should not corrupt a stable domain."""
+    with MemoryLayer(":memory:", auto_discover=True) as mem:
+        mem.write("User is a careful planner", domain="personality_trait")
+        for _ in range(8):
+            res = mem.observe(
+                "User did something out of character",
+                domain="personality_trait",
+                mismatch_magnitude=0.6,
+                source="weak_inference",
+            )
+        assert res.action == "logged_mismatch"
+        items = mem._active(domain="personality_trait")
+        assert len(items) == 1
+        assert "careful planner" in items[0].content
+
+
+def test_create_memory_auto_discover_flag():
+    from voltmem import create_memory
+
+    with create_memory(":memory:", auto_discover=True, embeddings=False) as mem:
+        assert mem.layer.auto_discover is True
+        row = mem.add("I live in Berlin")
+        assert row["action"] == "inserted"
+
+
+if __name__ == "__main__":
+    tests = [
+        test_domain_stats_empirical_volatility_rises_with_supersedes,
+        test_blend_volatility_requires_min_observations,
+        test_prior_anchored_ema_clamps_drift,
+        test_auto_discover_records_observations,
+        test_auto_discover_persists_across_sessions,
+        test_auto_discover_off_by_default,
+        test_weak_inference_does_not_supersede_stable_with_auto_discover,
+        test_create_memory_auto_discover_flag,
+    ]
+    failed = 0
+    for t in tests:
+        try:
+            t()
+            print(f"  PASS  {t.__name__}")
+        except Exception as exc:
+            failed += 1
+            print(f"  FAIL  {t.__name__}: {exc}")
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    raise SystemExit(1 if failed else 0)