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.
- memorydrift-3.0.0.dist-info/METADATA +146 -0
- memorydrift-3.0.0.dist-info/RECORD +15 -0
- memorydrift-3.0.0.dist-info/WHEEL +5 -0
- memorydrift-3.0.0.dist-info/top_level.txt +1 -0
- memorylayer/__init__.py +59 -0
- memorylayer/collective.py +135 -0
- memorylayer/consolidation.py +101 -0
- memorylayer/decay.py +241 -0
- memorylayer/embedding.py +37 -0
- memorylayer/emotion.py +243 -0
- memorylayer/fidelity.py +166 -0
- memorylayer/memory_store.py +280 -0
- memorylayer/prospective.py +96 -0
- memorylayer/reconsolidation.py +132 -0
- memorylayer/sleep.py +110 -0
|
@@ -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
|
+
)
|