memorydrift 3.0.0__py3-none-any.whl

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.

Potentially problematic release.


This version of memorydrift might be problematic. Click here for more details.

@@ -0,0 +1,146 @@
1
+ Metadata-Version: 2.4
2
+ Name: memorydrift
3
+ Version: 3.0.0
4
+ Summary: AI memory that decays, degrades, and drifts the way human memory does
5
+ Author-email: Mounica Goriparti <mounica.goriparti@gmail.com>
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Homepage, https://github.com/mounica-goriparti/memorylayer
8
+ Project-URL: Bug Tracker, https://github.com/mounica-goriparti/memorylayer/issues
9
+ Keywords: AI memory,cognitive AI,LLM,agent memory,episodic memory,memory decay,NLP
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ Provides-Extra: embed
22
+ Requires-Dist: sentence-transformers>=2.2; extra == "embed"
23
+ Provides-Extra: neural
24
+ Requires-Dist: transformers>=4.30; extra == "neural"
25
+ Requires-Dist: torch>=2.0; extra == "neural"
26
+ Provides-Extra: ui
27
+ Requires-Dist: streamlit>=1.30; extra == "ui"
28
+ Requires-Dist: plotly>=5.0; extra == "ui"
29
+ Requires-Dist: pandas>=2.0; extra == "ui"
30
+ Provides-Extra: full
31
+ Requires-Dist: sentence-transformers>=2.2; extra == "full"
32
+ Requires-Dist: transformers>=4.30; extra == "full"
33
+ Requires-Dist: torch>=2.0; extra == "full"
34
+
35
+ # MemoryLayer
36
+
37
+ AI memory that decays, degrades, and drifts the way human memory does.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ pip install memorylayer # pure-Python core, zero dependencies
43
+ pip install "memorylayer[embed]" # + real semantic embeddings (all-MiniLM-L6-v2)
44
+ pip install "memorylayer[full]" # + neural emotion classifier
45
+ ```
46
+
47
+ ## Quickstart
48
+
49
+ ```python
50
+ from memorylayer import MemoryStore, MemoryLayer
51
+
52
+ store = MemoryStore(auto_embed=True)
53
+
54
+ store.write("I saved the blacksmith's son", emotional_weight=0.9, age_at_encoding=28)
55
+ store.write("The dragon was defeated in the northern tower", emotional_weight=0.7)
56
+
57
+ for r in store.retrieve():
58
+ print(r.display_content) # "I clearly remember: I saved the blacksmith's son"
59
+ print(r.decay.fidelity) # VIVID / CLEAR / FADED / VAGUE / FEELING
60
+ ```
61
+
62
+ Spreading activation fires automatically — semantically similar memories surface together.
63
+
64
+ ## What makes it different
65
+
66
+ Every other AI memory system is a key-value store. MemoryLayer implements the neuroscience:
67
+
68
+ | Human memory property | MemoryLayer |
69
+ |---|---|
70
+ | Emotional memories last longer | `emotional_weight` stretches halflife up to 3× |
71
+ | Details fade before the gist | Fidelity degrades: VIVID → CLEAR → FADED → VAGUE → FEELING |
72
+ | Rehearsal keeps memories strong | `repetition_count` boosts stability (spaced repetition) |
73
+ | Related memories surface together | Spreading activation via semantic embeddings |
74
+ | Weak memories drift on recall | Reconsolidation: content rewrites toward current context |
75
+ | Childhood memories are hazy | Age-at-encoding: childhood amnesia + reminiscence bump (Rubin 1997) |
76
+ | Sleep consolidates the day | `simulate_sleep()` adds replay repetitions, tags CLEAR+ for promotion |
77
+
78
+ ## Memory layers
79
+
80
+ | Layer | Halflife | Use for |
81
+ |---|---|---|
82
+ | `WORKING` | ~1 hour | Active conversation context |
83
+ | `EPISODIC` | 1 year | Events and experiences |
84
+ | `SEMANTIC` | 5 years | Facts and knowledge |
85
+ | `PROSPECTIVE` | 3 days | Intentions that fade if unacted on |
86
+ | `IDENTITY` | Forever | Core beliefs and self-concept |
87
+
88
+ ## Advanced API
89
+
90
+ ```python
91
+ from memorylayer import (
92
+ # Prospective memory — intentions
93
+ write_intention, complete_intention, get_overdue_intentions,
94
+
95
+ # Collective memory — shared events, per-entity emotional weight
96
+ CollectiveMemoryStore,
97
+
98
+ # Sleep consolidation
99
+ simulate_sleep, SleepSession,
100
+
101
+ # Reconsolidation — memory drift on recall
102
+ reconsolidate_sync,
103
+ )
104
+
105
+ # Prospective memory
106
+ store = MemoryStore()
107
+ intention = write_intention(store, "Call the lawyer", due_in_days=3)
108
+ complete_intention(store, intention.id) # converts to episodic on completion
109
+
110
+ # Collective memory
111
+ shared = CollectiveMemoryStore()
112
+ event = shared.write_event(
113
+ "The team won the championship",
114
+ participants={"alice": 0.95, "bob": 0.40}, # alice scored; bob watched
115
+ )
116
+ alice_memories = shared.recall_for("alice") # stronger than bob's
117
+
118
+ # Sleep consolidation
119
+ result = simulate_sleep(store, SleepSession(quality=0.85, duration_hours=7.5))
120
+ print(f"Strengthened: {result.memories_strengthened}")
121
+ ```
122
+
123
+ ## Fidelity levels
124
+
125
+ When a memory is retrieved, its content is automatically degraded to match its strength:
126
+
127
+ ```
128
+ VIVID (> 0.70) "I clearly remember: she smiled at the coffee shop."
129
+ CLEAR (0.45–) "I remember: something about a coffee shop."
130
+ FADED (0.22–) "I vaguely recall: she smiled."
131
+ VAGUE (0.08–) "I have a faint sense that: she smiled…"
132
+ FEELING (0.03–) "I don't remember what happened, but I remember warmth and joy."
133
+ FORGOTTEN(< 0.03) [not returned — the memory is gone]
134
+ ```
135
+
136
+ ## Patent
137
+
138
+ MemoryLayer implements three novel mechanisms filed with the Indian Patent Office (June 2026):
139
+
140
+ 1. **Emotionally-modulated decay floor** — high-emotion memories asymptotically approach a floor rather than decaying to zero.
141
+ 2. **Fidelity-degraded retrieval** — content specificity decreases proportionally to computed temporal strength.
142
+ 3. **Post-retrieval reconsolidation** — weak memories are rewritten toward current context on each recall.
143
+
144
+ ---
145
+
146
+ *Author: Mounica Goriparti · mounica.goriparti@gmail.com*
@@ -0,0 +1,15 @@
1
+ memorylayer/__init__.py,sha256=HATu5P6kbYaQx7W2YoGZJJq7OGHshJV888A0sSxB3d0,2703
2
+ memorylayer/collective.py,sha256=5_i3qjJjO0XkB4pCoA7saA7ZY2H72HfD6BWy2abFZPE,4318
3
+ memorylayer/consolidation.py,sha256=-x70dSeLR1zWj2fUvymrUlYeMZRcHafTVabL_k9Wbqc,3139
4
+ memorylayer/decay.py,sha256=L8ODQtnjykLkRoZB_SrgU033lONFDSjtiF4WPq15a8Q,8973
5
+ memorylayer/embedding.py,sha256=srPJlZS6i2mc4gBWslvFkYHL6ZzgTcNoBCxHn2fDKYU,1099
6
+ memorylayer/emotion.py,sha256=P48h-WJHCye8YeIyoqICRQHstBv2SidbAfi8aSES8_c,9353
7
+ memorylayer/fidelity.py,sha256=264SPOevg6B1O3OTyP-GaZ-YnwLwjLFk4MYA2Y03InA,6252
8
+ memorylayer/memory_store.py,sha256=fUFVeLlNNuUA7NqfYtOwNR1GMGvkf2OfeukZiiQOB_8,9205
9
+ memorylayer/prospective.py,sha256=tt50oH39HPFuF17iBTNuwALXzWMhalW1XxkVQpy9JZU,2819
10
+ memorylayer/reconsolidation.py,sha256=qvM3AGwNRdrdjdS8Ct-xWjExQwlWc6LU3PqwABxgDz4,4748
11
+ memorylayer/sleep.py,sha256=91Kn4gf2ZS-TCmxI_fsTRgMcCZwZJcdunzMVTlDhI2U,3938
12
+ memorydrift-3.0.0.dist-info/METADATA,sha256=_H6HjIe7NWDwm_24LVDpxg4UvQS5lulFcLhCAnLQPA8,5813
13
+ memorydrift-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
14
+ memorydrift-3.0.0.dist-info/top_level.txt,sha256=DTRZGR5DH_oS0mlzIbkFe6qETAX3OQMkSiehlBvXcfY,12
15
+ memorydrift-3.0.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ memorylayer
@@ -0,0 +1,59 @@
1
+ """
2
+ MemoryLayer — AI That Remembers The Way You Do
3
+
4
+ Primary import:
5
+ from memorylayer import MemoryStore, MemoryLayer
6
+ """
7
+
8
+ # ── Primary API ───────────────────────────────────────────────────────────────
9
+ from .memory_store import MemoryStore, Memory, RetrievedMemory, spreading_activation
10
+ from .decay import (
11
+ MemoryLayer, FidelityLevel, DecayResult,
12
+ compute_strength,
13
+ age_encoding_factor, age_encoding_factor_smooth, emotional_early_floor,
14
+ )
15
+
16
+ # ── Emotion + Fidelity ────────────────────────────────────────────────────────
17
+ from .emotion import classify, neural_emotional_weight, NEURAL_AVAILABLE
18
+ from .fidelity import degrade_content, build_prompt_context
19
+
20
+ # ── Consolidation + Reconsolidation ──────────────────────────────────────────
21
+ from .consolidation import run_consolidation
22
+ from .reconsolidation import (
23
+ reconsolidate_sync, reconsolidate_async,
24
+ RECONSOLIDATION_THRESHOLD, MAX_RECONSOLIDATIONS,
25
+ )
26
+
27
+ # ── Extensions ────────────────────────────────────────────────────────────────
28
+ from .embedding import embed, get_embedder, EMBED_AVAILABLE
29
+ from .prospective import (
30
+ write_intention, complete_intention,
31
+ get_pending_intentions, get_overdue_intentions, is_overdue,
32
+ )
33
+ from .collective import CollectiveMemoryStore, CollectiveMemory, EntityRecall
34
+ from .sleep import simulate_sleep, SleepSession, SleepConsolidationResult
35
+
36
+ __version__ = "3.0.0"
37
+ __author__ = "Mounica Goriparti"
38
+ __license__ = "Proprietary"
39
+ __all__ = [
40
+ # Core
41
+ "MemoryStore", "Memory", "RetrievedMemory", "spreading_activation",
42
+ "MemoryLayer", "FidelityLevel", "DecayResult",
43
+ # Emotion + Fidelity
44
+ "classify", "neural_emotional_weight", "NEURAL_AVAILABLE",
45
+ "degrade_content", "build_prompt_context",
46
+ # Consolidation
47
+ "run_consolidation",
48
+ "reconsolidate_sync", "reconsolidate_async",
49
+ "RECONSOLIDATION_THRESHOLD", "MAX_RECONSOLIDATIONS",
50
+ # Embeddings
51
+ "embed", "get_embedder", "EMBED_AVAILABLE",
52
+ # Prospective
53
+ "write_intention", "complete_intention",
54
+ "get_pending_intentions", "get_overdue_intentions", "is_overdue",
55
+ # Collective
56
+ "CollectiveMemoryStore", "CollectiveMemory", "EntityRecall",
57
+ # Sleep
58
+ "simulate_sleep", "SleepSession", "SleepConsolidationResult",
59
+ ]
@@ -0,0 +1,135 @@
1
+ """
2
+ MemoryLayer — Collective Memory
3
+
4
+ Shared events with per-entity emotional weights.
5
+ Models how different people remember the same event differently:
6
+ Alice scored the winning goal — her memory stays vivid for decades.
7
+ Bob watched from the stands — his fades to a faint impression in a few years.
8
+
9
+ Research: Halbwachs (1992) — On Collective Memory
10
+ Welzer et al. (1995) — Collective and individual memory
11
+ Roediger & Abel (2015) — Collective Memory: A New Arena of Cognitive Study
12
+ """
13
+
14
+ import math
15
+ import time
16
+ import uuid
17
+ from dataclasses import dataclass, field
18
+ from typing import Dict, List, Optional
19
+
20
+ from .decay import MemoryLayer, FidelityLevel, compute_strength, DecayResult
21
+
22
+
23
+ @dataclass
24
+ class CollectiveMemory:
25
+ id: str
26
+ content: str
27
+ created_at: float
28
+ tags: List[str]
29
+ entity_weights: Dict[str, float] # entity_id → emotional_weight
30
+ metadata: dict = field(default_factory=dict)
31
+
32
+
33
+ @dataclass
34
+ class EntityRecall:
35
+ event: CollectiveMemory
36
+ entity_id: str
37
+ emotional_weight: float
38
+ decay: DecayResult
39
+
40
+
41
+ class CollectiveMemoryStore:
42
+ """
43
+ Stores events shared between multiple entities.
44
+ Each entity recalls the same event through their own emotional weight —
45
+ same moment, different memory strength.
46
+ """
47
+
48
+ def __init__(self):
49
+ self._events: Dict[str, CollectiveMemory] = {}
50
+
51
+ def write_event(
52
+ self,
53
+ content: str,
54
+ participants: Dict[str, float],
55
+ tags: Optional[List[str]] = None,
56
+ now: Optional[float] = None,
57
+ metadata: Optional[dict] = None,
58
+ ) -> CollectiveMemory:
59
+ """
60
+ Record a shared event.
61
+
62
+ Args:
63
+ content: Description of the shared event.
64
+ participants: Mapping of entity_id → emotional_weight (0–1).
65
+ """
66
+ ts = now or time.time()
67
+ event = CollectiveMemory(
68
+ id=str(uuid.uuid4()),
69
+ content=content,
70
+ created_at=ts,
71
+ tags=tags or [],
72
+ entity_weights=dict(participants),
73
+ metadata=metadata or {},
74
+ )
75
+ self._events[event.id] = event
76
+ return event
77
+
78
+ def recall_for(
79
+ self,
80
+ entity_id: str,
81
+ now: Optional[float] = None,
82
+ importance: float = 0.70,
83
+ ) -> List[EntityRecall]:
84
+ """
85
+ Return all events accessible to `entity_id`, ordered by strength.
86
+ Non-participants and forgotten memories are excluded.
87
+ """
88
+ ts = now or time.time()
89
+ results = []
90
+ for event in self._events.values():
91
+ ew = event.entity_weights.get(entity_id)
92
+ if ew is None:
93
+ continue
94
+ days = (ts - event.created_at) / 86400.0
95
+ decay = compute_strength(
96
+ days_elapsed=days,
97
+ emotional_weight=ew,
98
+ repetition_count=0,
99
+ importance=importance,
100
+ layer=MemoryLayer.EPISODIC,
101
+ )
102
+ if decay.fidelity != FidelityLevel.FORGOTTEN:
103
+ results.append(EntityRecall(
104
+ event=event,
105
+ entity_id=entity_id,
106
+ emotional_weight=ew,
107
+ decay=decay,
108
+ ))
109
+ results.sort(key=lambda r: r.decay.strength, reverse=True)
110
+ return results
111
+
112
+ def divergence(self, event_id: str) -> Optional[float]:
113
+ """
114
+ Emotional divergence across participants for one event.
115
+ Returns the standard deviation of emotional weights,
116
+ or None if the event has fewer than 2 participants.
117
+
118
+ 0.0 = everyone remembers it the same way.
119
+ ~0.45 = maximum disagreement (one person at 0.95, another at 0.05).
120
+ """
121
+ event = self._events.get(event_id)
122
+ if event is None or len(event.entity_weights) < 2:
123
+ return None
124
+ weights = list(event.entity_weights.values())
125
+ mean = sum(weights) / len(weights)
126
+ variance = sum((w - mean) ** 2 for w in weights) / len(weights)
127
+ return round(math.sqrt(variance), 4)
128
+
129
+ def stats(self) -> dict:
130
+ return {
131
+ "total_events": len(self._events),
132
+ "total_participant_slots": sum(
133
+ len(e.entity_weights) for e in self._events.values()
134
+ ),
135
+ }
@@ -0,0 +1,101 @@
1
+ """
2
+ MemoryLayer — Consolidation Pipeline
3
+
4
+ Time-triggered episodic → semantic compression (mirrors human sleep consolidation).
5
+ Episodic memories that are old enough and strong enough get abstracted into
6
+ compressed semantic facts that decay much more slowly.
7
+
8
+ Trigger: memories older than consolidation_threshold_days and still CLEAR or above.
9
+ """
10
+
11
+ import time
12
+ from dataclasses import dataclass
13
+ from typing import List, Optional, Tuple
14
+
15
+ from .decay import MemoryLayer, FidelityLevel
16
+ from .memory_store import MemoryStore, Memory, RetrievedMemory
17
+
18
+
19
+ @dataclass
20
+ class ConsolidationResult:
21
+ consolidated: int # number of episodes compressed
22
+ skipped: int # too old/weak or already semantic
23
+ new_semantic_ids: List[str]
24
+ summary: str
25
+
26
+
27
+ def _compress_content(content: str) -> str:
28
+ """
29
+ Produce a compressed semantic fact from an episodic memory.
30
+ Strategy: keep the core factual claim, drop emotional/temporal qualifiers.
31
+ Heuristic: take the main clause (strip subordinate clauses starting with
32
+ 'because', 'when', 'after', etc.) and trim to ≤ 80 chars.
33
+ """
34
+ import re
35
+ # Strip subordinate clause markers
36
+ text = re.sub(
37
+ r"\b(because|when|after|before|although|while|since|as|if|unless)\b.*$",
38
+ "", content, flags=re.IGNORECASE
39
+ ).strip().rstrip(".,;")
40
+
41
+ # Remove first-person hedging
42
+ text = re.sub(r"^(I (felt|was|became|got|realized|noticed|felt)\s+)", "", text, flags=re.IGNORECASE)
43
+
44
+ # Truncate
45
+ if len(text) > 120:
46
+ words = text.split()
47
+ text = " ".join(words[:15]) + "…"
48
+
49
+ return text.strip() or content[:80]
50
+
51
+
52
+ def run_consolidation(
53
+ store: MemoryStore,
54
+ consolidation_threshold_days: float = 7.0,
55
+ min_fidelity: FidelityLevel = FidelityLevel.CLEAR,
56
+ now: Optional[float] = None,
57
+ ) -> ConsolidationResult:
58
+ """
59
+ Scan episodic memories older than threshold.
60
+ Compress CLEAR+ memories to semantic layer.
61
+ Returns summary of what was consolidated.
62
+ """
63
+ ts = now or time.time()
64
+ threshold_sec = consolidation_threshold_days * 86400
65
+
66
+ candidates = [
67
+ r for r in store.all_with_decay(now=ts)
68
+ if r.memory.layer == MemoryLayer.EPISODIC.value
69
+ and (ts - r.memory.created_at) >= threshold_sec
70
+ and r.decay.fidelity not in (FidelityLevel.FORGOTTEN, FidelityLevel.VAGUE)
71
+ ]
72
+
73
+ consolidated = 0
74
+ new_ids = []
75
+
76
+ for rm in candidates:
77
+ compressed = _compress_content(rm.memory.content)
78
+ new_mem = store.consolidate_to_semantic(
79
+ memory_id=rm.memory.id,
80
+ compressed_content=compressed,
81
+ now=ts,
82
+ )
83
+ new_ids.append(new_mem.id)
84
+ consolidated += 1
85
+
86
+ all_episodic = sum(
87
+ 1 for r in store.all_with_decay(now=ts)
88
+ if r.memory.layer == MemoryLayer.EPISODIC.value
89
+ )
90
+
91
+ summary = (
92
+ f"Consolidated {consolidated} episodic → semantic. "
93
+ f"Remaining episodic: {all_episodic}."
94
+ )
95
+
96
+ return ConsolidationResult(
97
+ consolidated=consolidated,
98
+ skipped=len(candidates) - consolidated,
99
+ new_semantic_ids=new_ids,
100
+ summary=summary,
101
+ )