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,280 @@
1
+ """
2
+ MemoryLayer — Memory Store
3
+
4
+ Core storage layer. Handles write, retrieve, tag/layer filtering,
5
+ spreading activation, and automatic emotional classification.
6
+ """
7
+
8
+ import math
9
+ import time
10
+ import uuid
11
+ from dataclasses import dataclass, field
12
+ from typing import Dict, List, Optional, Tuple
13
+
14
+ from .decay import (
15
+ compute_strength, FidelityLevel, MemoryLayer, DecayResult,
16
+ age_encoding_factor,
17
+ )
18
+ from .emotion import classify
19
+ from .fidelity import degrade_content, FidelityResult
20
+
21
+
22
+ @dataclass
23
+ class Memory:
24
+ id: str
25
+ content: str
26
+ layer: str
27
+ tags: List[str]
28
+ importance: float
29
+ emotional_weight: float
30
+ dominant_emotion: str
31
+ repetition_count: int
32
+ created_at: float
33
+ last_accessed: float
34
+ age_at_encoding: Optional[float]
35
+ metadata: dict
36
+ last_reconsolidated: float
37
+ reconsolidation_count: int
38
+ original_content: str
39
+
40
+
41
+ @dataclass
42
+ class RetrievedMemory:
43
+ memory: Memory
44
+ decay: DecayResult
45
+ display_content: str
46
+ fidelity_result: FidelityResult
47
+ activation_boost: float = 0.0
48
+
49
+
50
+ # ── Spreading activation ──────────────────────────────────────────────────────
51
+
52
+ def _cosine_similarity(a: list, b: list) -> float:
53
+ dot = sum(x * y for x, y in zip(a, b))
54
+ mag_a = math.sqrt(sum(x * x for x in a))
55
+ mag_b = math.sqrt(sum(x * x for x in b))
56
+ if mag_a == 0 or mag_b == 0:
57
+ return 0.0
58
+ return dot / (mag_a * mag_b)
59
+
60
+
61
+ def spreading_activation(
62
+ source: Memory,
63
+ all_memories: List[Memory],
64
+ decay_fn,
65
+ now: float,
66
+ boost: float = 0.3,
67
+ sim_threshold: float = 0.5,
68
+ emotion_tolerance: float = 0.5,
69
+ ) -> List[Tuple[str, float]]:
70
+ """
71
+ Find memories semantically similar to `source` and return
72
+ (memory_id, activation_boost) pairs. Excludes:
73
+ - memories without embeddings
74
+ - emotionally incompatible memories (outside emotion_tolerance)
75
+ - memories at or below their floor (somatic remnants, not retrievable)
76
+ """
77
+ src_emb = source.metadata.get("embedding") if source.metadata else None
78
+ if src_emb is None:
79
+ return []
80
+
81
+ activated = []
82
+ for mem in all_memories:
83
+ if mem.id == source.id:
84
+ continue
85
+ mem_emb = mem.metadata.get("embedding") if mem.metadata else None
86
+ if mem_emb is None:
87
+ continue
88
+
89
+ sim = _cosine_similarity(src_emb, mem_emb)
90
+ if sim < sim_threshold:
91
+ continue
92
+
93
+ if abs(mem.emotional_weight - source.emotional_weight) > emotion_tolerance:
94
+ continue
95
+
96
+ dr = decay_fn(mem, now)
97
+ # Exclude if truly forgotten OR only alive due to emotional floor (somatic trace)
98
+ if dr.fidelity == FidelityLevel.FORGOTTEN or dr.strength <= dr.floor:
99
+ continue
100
+
101
+ activated.append((mem.id, boost * sim))
102
+
103
+ return activated
104
+
105
+
106
+ # ── MemoryStore ───────────────────────────────────────────────────────────────
107
+
108
+ class MemoryStore:
109
+ def __init__(self, auto_embed: bool = False):
110
+ self._memories: Dict[str, Memory] = {}
111
+ self._decay = self._compute_decay
112
+ self._auto_embed = auto_embed
113
+
114
+ def _compute_decay(self, memory: Memory, now: float) -> DecayResult:
115
+ days = (now - memory.created_at) / 86400.0
116
+ layer = MemoryLayer(memory.layer)
117
+ return compute_strength(
118
+ days_elapsed=days,
119
+ emotional_weight=memory.emotional_weight,
120
+ repetition_count=memory.repetition_count,
121
+ importance=memory.importance,
122
+ layer=layer,
123
+ age_at_encoding=memory.age_at_encoding,
124
+ )
125
+
126
+ def write(
127
+ self,
128
+ content: str,
129
+ layer: MemoryLayer = MemoryLayer.EPISODIC,
130
+ tags: Optional[List[str]] = None,
131
+ emotional_weight: Optional[float] = None,
132
+ importance: float = 0.7,
133
+ now: Optional[float] = None,
134
+ age_at_encoding: Optional[float] = None,
135
+ metadata: Optional[dict] = None,
136
+ ) -> Memory:
137
+ ts = now or time.time()
138
+
139
+ # Auto-generate embedding if enabled and not already provided
140
+ if self._auto_embed and "embedding" not in (metadata or {}):
141
+ try:
142
+ from .embedding import embed as _embed
143
+ emb = _embed(content)
144
+ if emb is not None:
145
+ metadata = {**(metadata or {}), "embedding": emb}
146
+ except Exception:
147
+ pass
148
+
149
+ if emotional_weight is None:
150
+ result = classify(content)
151
+ ew = result.weight
152
+ dominant = result.dominant_emotion
153
+ else:
154
+ ew = emotional_weight
155
+ dominant = "manual"
156
+
157
+ mem = Memory(
158
+ id=str(uuid.uuid4()),
159
+ content=content,
160
+ layer=layer.value,
161
+ tags=tags or [],
162
+ importance=importance,
163
+ emotional_weight=ew,
164
+ dominant_emotion=dominant,
165
+ repetition_count=0,
166
+ created_at=ts,
167
+ last_accessed=ts,
168
+ age_at_encoding=age_at_encoding,
169
+ metadata=metadata or {},
170
+ last_reconsolidated=0.0,
171
+ reconsolidation_count=0,
172
+ original_content="",
173
+ )
174
+ self._memories[mem.id] = mem
175
+ return mem
176
+
177
+ def _make_retrieved(
178
+ self,
179
+ memory: Memory,
180
+ now: float,
181
+ activation_boost: float = 0.0,
182
+ increment_recall: bool = False,
183
+ ) -> RetrievedMemory:
184
+ if increment_recall:
185
+ memory.repetition_count += 1
186
+ memory.last_accessed = now
187
+ dr = self._compute_decay(memory, now)
188
+ fr = degrade_content(memory.content, dr.fidelity)
189
+ return RetrievedMemory(
190
+ memory=memory,
191
+ decay=dr,
192
+ display_content=fr.displayed_content,
193
+ fidelity_result=fr,
194
+ activation_boost=activation_boost,
195
+ )
196
+
197
+ def retrieve(
198
+ self,
199
+ query_tags: Optional[List[str]] = None,
200
+ layer: Optional[MemoryLayer] = None,
201
+ now: Optional[float] = None,
202
+ spreading: bool = True,
203
+ increment_recall: bool = True,
204
+ ) -> List[RetrievedMemory]:
205
+ ts = now or time.time()
206
+ candidates = list(self._memories.values())
207
+
208
+ if layer is not None:
209
+ candidates = [m for m in candidates if m.layer == layer.value]
210
+ if query_tags:
211
+ candidates = [m for m in candidates if any(t in m.tags for t in query_tags)]
212
+
213
+ results = []
214
+ for mem in candidates:
215
+ rm = self._make_retrieved(mem, ts, increment_recall=increment_recall)
216
+ if rm.decay.fidelity != FidelityLevel.FORGOTTEN:
217
+ results.append(rm)
218
+
219
+ if spreading and results:
220
+ top = max(results, key=lambda r: r.decay.strength)
221
+ all_mems = list(self._memories.values())
222
+ boost_map = {mid: b for mid, b in
223
+ spreading_activation(top.memory, all_mems, self._decay, ts)}
224
+ for rm in results:
225
+ if rm.memory.id in boost_map:
226
+ rm.activation_boost = boost_map[rm.memory.id]
227
+
228
+ results.sort(key=lambda r: r.decay.strength + r.activation_boost, reverse=True)
229
+ return results
230
+
231
+ def retrieve_one(
232
+ self,
233
+ memory_id: str,
234
+ increment_recall: bool = True,
235
+ now: Optional[float] = None,
236
+ ) -> Optional[RetrievedMemory]:
237
+ mem = self._memories.get(memory_id)
238
+ if mem is None:
239
+ return None
240
+ ts = now or time.time()
241
+ return self._make_retrieved(mem, ts, increment_recall=increment_recall)
242
+
243
+ def all_with_decay(self, now: Optional[float] = None) -> List[RetrievedMemory]:
244
+ ts = now or time.time()
245
+ return [self._make_retrieved(m, ts) for m in self._memories.values()]
246
+
247
+ def consolidate_to_semantic(
248
+ self,
249
+ memory_id: str,
250
+ compressed_content: str,
251
+ now: Optional[float] = None,
252
+ ) -> Memory:
253
+ ts = now or time.time()
254
+ original = self._memories.get(memory_id)
255
+ new_mem = self.write(
256
+ content=compressed_content,
257
+ layer=MemoryLayer.SEMANTIC,
258
+ tags=original.tags if original else [],
259
+ emotional_weight=original.emotional_weight if original else 0.0,
260
+ importance=original.importance if original else 0.7,
261
+ now=ts,
262
+ age_at_encoding=original.age_at_encoding if original else None,
263
+ )
264
+ if original:
265
+ del self._memories[memory_id]
266
+ return new_mem
267
+
268
+ def stats(self) -> dict:
269
+ ts = time.time()
270
+ all_rm = self.all_with_decay(now=ts)
271
+ active = sum(1 for rm in all_rm if rm.decay.fidelity != FidelityLevel.FORGOTTEN)
272
+ by_layer: Dict[str, int] = {}
273
+ for rm in all_rm:
274
+ by_layer[rm.memory.layer] = by_layer.get(rm.memory.layer, 0) + 1
275
+ return {
276
+ "total": len(self._memories),
277
+ "active": active,
278
+ "forgotten": len(self._memories) - active,
279
+ "by_layer": by_layer,
280
+ }
@@ -0,0 +1,96 @@
1
+ """
2
+ MemoryLayer — Prospective Memory
3
+
4
+ Intentions and plans that decay quickly if not acted upon.
5
+ Halflife: 3 days — an unfulfilled intention fades within a week.
6
+ Acting on the intention converts it to an episodic memory.
7
+
8
+ Research: McDaniel & Einstein (2007) — Prospective Memory: An Overview and Synthesis
9
+ Kliegel et al. (2008) — Prospective Memory: Cognitive, Neuroscience, and
10
+ Applied Perspectives
11
+ """
12
+
13
+ import time
14
+ from typing import List, Optional
15
+
16
+ from .memory_store import MemoryStore, Memory, RetrievedMemory
17
+ from .decay import MemoryLayer
18
+
19
+
20
+ def write_intention(
21
+ store: MemoryStore,
22
+ content: str,
23
+ due_in_days: float = 7.0,
24
+ importance: float = 0.80,
25
+ tags: Optional[List[str]] = None,
26
+ now: Optional[float] = None,
27
+ ) -> Memory:
28
+ """
29
+ Store a prospective memory (intention / plan).
30
+ Due date is recorded in metadata["due_at"].
31
+ """
32
+ ts = now or time.time()
33
+ return store.write(
34
+ content=content,
35
+ layer=MemoryLayer.PROSPECTIVE,
36
+ importance=importance,
37
+ emotional_weight=0.30,
38
+ tags=tags or [],
39
+ metadata={"due_at": ts + due_in_days * 86400},
40
+ now=ts,
41
+ )
42
+
43
+
44
+ def is_overdue(memory: Memory, now: Optional[float] = None) -> bool:
45
+ """Return True if the intention's due date has passed without completion."""
46
+ ts = now or time.time()
47
+ return ts > memory.metadata.get("due_at", 0)
48
+
49
+
50
+ def complete_intention(
51
+ store: MemoryStore,
52
+ memory_id: str,
53
+ now: Optional[float] = None,
54
+ ) -> Memory:
55
+ """
56
+ Mark a prospective memory as completed.
57
+ Removes the prospective entry and writes a new episodic memory
58
+ capturing the act of completion.
59
+ """
60
+ ts = now or time.time()
61
+ mem = store._memories.get(memory_id)
62
+ if mem is None:
63
+ raise KeyError(f"Memory {memory_id!r} not found")
64
+
65
+ new_mem = store.write(
66
+ content=f"Completed: {mem.content}",
67
+ layer=MemoryLayer.EPISODIC,
68
+ importance=mem.importance,
69
+ emotional_weight=0.50, # mild satisfaction of getting it done
70
+ tags=list(mem.tags),
71
+ now=ts,
72
+ )
73
+ del store._memories[memory_id]
74
+ return new_mem
75
+
76
+
77
+ def get_pending_intentions(
78
+ store: MemoryStore,
79
+ now: Optional[float] = None,
80
+ ) -> List[RetrievedMemory]:
81
+ """Return all prospective memories that have not yet been forgotten."""
82
+ return store.retrieve(
83
+ layer=MemoryLayer.PROSPECTIVE,
84
+ now=now,
85
+ increment_recall=False,
86
+ )
87
+
88
+
89
+ def get_overdue_intentions(
90
+ store: MemoryStore,
91
+ now: Optional[float] = None,
92
+ ) -> List[RetrievedMemory]:
93
+ """Return prospective memories that are past their due date."""
94
+ ts = now or time.time()
95
+ return [r for r in get_pending_intentions(store, now=ts)
96
+ if is_overdue(r.memory, now=ts)]
@@ -0,0 +1,132 @@
1
+ """
2
+ MemoryLayer — Memory Reconsolidation
3
+
4
+ Every time a weak memory is recalled, it is slightly modified by current context.
5
+ Strong memories (≥ 0.45) resist modification — they are stable and reliable.
6
+ Weak memories fill gaps from the current context — they drift over time.
7
+
8
+ Research basis:
9
+ Nader & Hardt (2009) — reconsolidation as labile post-retrieval window
10
+ Dudai (2012) — reconsolidation: a circuit-level analysis
11
+ Hupbach et al. (2008) — contextual cueing drives memory modification
12
+
13
+ Patent relevance:
14
+ Third novel mechanism beyond Claim 1 (decay+floor) and Claim 2 (fidelity).
15
+ No other AI memory system implements post-retrieval content drift.
16
+
17
+ Usage:
18
+ # Synchronous (for scripts, tests)
19
+ new_content = reconsolidate_sync(memory, query, strength, llm_fn)
20
+
21
+ # Async (for FastAPI, async AI pipelines)
22
+ new_content = await reconsolidate_async(memory, query, strength, async_llm_fn)
23
+ """
24
+
25
+ import time
26
+ from typing import Callable, Optional, Awaitable
27
+
28
+ RECONSOLIDATION_THRESHOLD = 0.45 # memories weaker than this are reconsolidated on recall
29
+ RECONSOLIDATION_FLOOR = 0.03 # FEELING-level memories are too faint to reconsolidate
30
+ MAX_RECONSOLIDATIONS = 3 # after this many drifts the trace stabilises
31
+
32
+
33
+ def _build_reconsolidation_prompt(
34
+ original_content: str,
35
+ current_query: str,
36
+ current_strength: float,
37
+ ) -> str:
38
+ influence = round(1.0 - current_strength, 2)
39
+ return (
40
+ f"Original memory (confidence {current_strength:.0%}):\n"
41
+ f"{original_content}\n\n"
42
+ f"Current context the person is thinking about:\n"
43
+ f"{current_query}\n\n"
44
+ f"Given that this memory is old and {influence:.0%} uncertain, "
45
+ f"what would the person likely remember now? "
46
+ f"They may unconsciously fill gaps with current context. "
47
+ f"One sentence only."
48
+ )
49
+
50
+
51
+ def reconsolidate_sync(
52
+ memory, # Memory dataclass
53
+ current_query: str,
54
+ current_strength: float,
55
+ llm_fn: Callable[[str], str],
56
+ now: Optional[float] = None,
57
+ ) -> str:
58
+ """
59
+ Synchronous reconsolidation.
60
+
61
+ Strong memories (≥ RECONSOLIDATION_THRESHOLD) are returned unchanged.
62
+ FEELING-level memories (≤ RECONSOLIDATION_FLOOR) are too faint to modify.
63
+ All others are blended with current_query via llm_fn.
64
+
65
+ The memory.content is updated in-place — the drift is permanent.
66
+
67
+ Args:
68
+ memory: Memory object being recalled
69
+ current_query: The query/context that triggered recall
70
+ current_strength: Current decay strength (0.0–1.0)
71
+ llm_fn: Callable(prompt: str) -> str
72
+ now: Timestamp (default: time.time())
73
+
74
+ Returns:
75
+ The reconsolidated content string.
76
+ """
77
+ if current_strength >= RECONSOLIDATION_THRESHOLD:
78
+ return memory.content # strong — resists modification
79
+
80
+ if current_strength <= RECONSOLIDATION_FLOOR:
81
+ return memory.content # FEELING-level — too faint to reshape
82
+
83
+ if getattr(memory, "reconsolidation_count", 0) >= MAX_RECONSOLIDATIONS:
84
+ return memory.content # trace has stabilised — further drift capped
85
+
86
+ # Preserve the original on first drift
87
+ if not getattr(memory, "original_content", ""):
88
+ memory.original_content = memory.content
89
+
90
+ prompt = _build_reconsolidation_prompt(
91
+ memory.content, current_query, current_strength
92
+ )
93
+ reconsolidated = llm_fn(prompt)
94
+
95
+ memory.content = reconsolidated
96
+ memory.last_reconsolidated = now or time.time()
97
+ memory.reconsolidation_count = getattr(memory, "reconsolidation_count", 0) + 1
98
+ return reconsolidated
99
+
100
+
101
+ async def reconsolidate_async(
102
+ memory,
103
+ current_query: str,
104
+ current_strength: float,
105
+ llm_fn: Callable[[str], Awaitable[str]],
106
+ now: Optional[float] = None,
107
+ ) -> str:
108
+ """
109
+ Async reconsolidation — llm_fn is an async callable.
110
+ Same logic as reconsolidate_sync but awaits the LLM call.
111
+ """
112
+ if current_strength >= RECONSOLIDATION_THRESHOLD:
113
+ return memory.content
114
+
115
+ if current_strength <= RECONSOLIDATION_FLOOR:
116
+ return memory.content
117
+
118
+ if getattr(memory, "reconsolidation_count", 0) >= MAX_RECONSOLIDATIONS:
119
+ return memory.content
120
+
121
+ if not getattr(memory, "original_content", ""):
122
+ memory.original_content = memory.content
123
+
124
+ prompt = _build_reconsolidation_prompt(
125
+ memory.content, current_query, current_strength
126
+ )
127
+ reconsolidated = await llm_fn(prompt)
128
+
129
+ memory.content = reconsolidated
130
+ memory.last_reconsolidated = now or time.time()
131
+ memory.reconsolidation_count = getattr(memory, "reconsolidation_count", 0) + 1
132
+ return reconsolidated
memorylayer/sleep.py ADDED
@@ -0,0 +1,110 @@
1
+ """
2
+ MemoryLayer — Sleep Simulation
3
+
4
+ Sleep quality modulates memory consolidation.
5
+ NREM (slow-wave): rehearses and strengthens recent episodic memories.
6
+ REM: integrates emotional memories, prunes noise.
7
+ Poor sleep: weak consolidation, faster subsequent decay.
8
+
9
+ Mechanism:
10
+ - Good sleep (effectiveness ≥ 0.65) → adds replay repetitions (boosts stability)
11
+ - Great sleep (effectiveness ≥ 0.65) → tags CLEAR+ episodic as 'sleep_consolidated'
12
+ - Poor sleep (effectiveness < 0.40) → no boost applied
13
+
14
+ Research:
15
+ Walker (2017) — Why We Sleep
16
+ Diekelmann (2010) — The memory function of sleep (Nature Rev Neuroscience)
17
+ Stickgold (2005) — Sleep-dependent memory consolidation (Nature)
18
+ """
19
+
20
+ import time
21
+ from dataclasses import dataclass
22
+ from typing import Optional
23
+
24
+ from .memory_store import MemoryStore
25
+ from .decay import MemoryLayer, FidelityLevel
26
+
27
+
28
+ @dataclass
29
+ class SleepSession:
30
+ quality: float # 0.0 (fragmented / no sleep) to 1.0 (perfect)
31
+ duration_hours: float # total hours of sleep
32
+ rem_fraction: float = 0.25 # fraction spent in REM (healthy adult ≈ 0.25)
33
+
34
+
35
+ @dataclass
36
+ class SleepConsolidationResult:
37
+ memories_strengthened: int # memories that received replay repetitions
38
+ memories_consolidated: int # episodic memories tagged as sleep-consolidated
39
+ sleep_quality: float
40
+ effectiveness: float # computed overall effectiveness (0–1)
41
+
42
+
43
+ def _sleep_effectiveness(session: SleepSession) -> float:
44
+ """
45
+ Compute overall sleep effectiveness from quality, duration, and REM fraction.
46
+ quality → 50% of score
47
+ duration → 30% (optimal = 8h; capped at 1.0)
48
+ REM fraction → 20% (optimal = 0.25; penalty for deviation)
49
+ """
50
+ duration_score = min(1.0, session.duration_hours / 8.0)
51
+ rem_deviation = abs(session.rem_fraction - 0.25) * 4.0
52
+ rem_score = max(0.0, 1.0 - rem_deviation)
53
+ return round(
54
+ session.quality * 0.50
55
+ + duration_score * 0.30
56
+ + rem_score * 0.20,
57
+ 3,
58
+ )
59
+
60
+
61
+ def simulate_sleep(
62
+ store: MemoryStore,
63
+ session: SleepSession,
64
+ now: Optional[float] = None,
65
+ ) -> SleepConsolidationResult:
66
+ """
67
+ Apply one sleep session's consolidation effects to the memory store in-place.
68
+
69
+ Effects:
70
+ Strengthening — NREM replay: adds up to 2 extra repetitions on active memories.
71
+ Consolidation — Tags CLEAR+ episodic memories as 'sleep_consolidated'
72
+ (marks them for the episodic→semantic pipeline).
73
+ Weak sleep — effectiveness < 0.40 provides no benefit.
74
+ """
75
+ ts = now or time.time()
76
+ effectiveness = _sleep_effectiveness(session)
77
+ strengthened = 0
78
+ consolidated = 0
79
+
80
+ for rm in store.all_with_decay(now=ts):
81
+ mem = rm.memory
82
+ fid = rm.decay.fidelity
83
+
84
+ if fid == FidelityLevel.FORGOTTEN:
85
+ continue
86
+ if mem.layer == MemoryLayer.IDENTITY.value:
87
+ continue
88
+
89
+ # NREM replay: add repetition boost for accessible memories
90
+ if (effectiveness >= 0.40
91
+ and fid in (FidelityLevel.VIVID, FidelityLevel.CLEAR, FidelityLevel.FADED)):
92
+ replay = round(effectiveness * 2) # 1–2 extra repetitions
93
+ if replay > 0:
94
+ mem.repetition_count += replay
95
+ strengthened += 1
96
+
97
+ # Sleep consolidation tag: CLEAR+ episodic on good sleep
98
+ if (effectiveness >= 0.65
99
+ and mem.layer == MemoryLayer.EPISODIC.value
100
+ and fid in (FidelityLevel.VIVID, FidelityLevel.CLEAR)
101
+ and "sleep_consolidated" not in mem.tags):
102
+ mem.tags.append("sleep_consolidated")
103
+ consolidated += 1
104
+
105
+ return SleepConsolidationResult(
106
+ memories_strengthened=strengthened,
107
+ memories_consolidated=consolidated,
108
+ sleep_quality=session.quality,
109
+ effectiveness=effectiveness,
110
+ )