VibecoderMcSwaggins commited on
Commit
b074f88
Β·
1 Parent(s): 7719726

docs: add SPEC_08 for memory layer integration

Browse files

SPEC_08 documents the plan to integrate the structured memory layer
(built in SPEC_07 as "God Mode") into Simple and Advanced modes.

Key points:
- Memory should be a shared LAYER, not a separate MODE
- Extract ResearchMemory service from LangGraph nodes
- Wire into existing orchestrators
- Remove "God Mode" from UI post-integration

Also updates ACTIVE_BUGS.md to track this as P1 post-hackathon work.

Related: Issue #73, PR #72

docs/bugs/ACTIVE_BUGS.md CHANGED
@@ -10,14 +10,22 @@
10
 
11
  ## P3 - Architecture/Enhancement
12
 
13
- ### ~~P3 - Missing Structured Cognitive Memory~~ FIXED
14
  **File:** `P3_ARCHITECTURAL_GAP_STRUCTURED_MEMORY.md`
15
  **Spec:** [SPEC_07_LANGGRAPH_MEMORY_ARCH.md](../specs/SPEC_07_LANGGRAPH_MEMORY_ARCH.md)
16
- **Commit:** (Current)
17
 
18
  **Problem:** AdvancedOrchestrator uses chat-based state (context drift on long runs).
19
  **Solution:** Implemented LangGraph StateGraph with explicit hypothesis/conflict tracking (`src/agents/graph`).
20
- **Status:** Implemented in "God Mode".
 
 
 
 
 
 
 
 
21
 
22
  ### P3 - Ephemeral Memory (No Persistence)
23
  **File:** `P3_ARCHITECTURAL_GAP_EPHEMERAL_MEMORY.md`
 
10
 
11
  ## P3 - Architecture/Enhancement
12
 
13
+ ### ~~P3 - Missing Structured Cognitive Memory~~ FIXED (Phase 1)
14
  **File:** `P3_ARCHITECTURAL_GAP_STRUCTURED_MEMORY.md`
15
  **Spec:** [SPEC_07_LANGGRAPH_MEMORY_ARCH.md](../specs/SPEC_07_LANGGRAPH_MEMORY_ARCH.md)
16
+ **PR:** [#72](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/pull/72)
17
 
18
  **Problem:** AdvancedOrchestrator uses chat-based state (context drift on long runs).
19
  **Solution:** Implemented LangGraph StateGraph with explicit hypothesis/conflict tracking (`src/agents/graph`).
20
+ **Status:** βœ… Memory layer built. ⏳ Integration pending (SPEC_08).
21
+
22
+ ### P1 - Memory Layer Not Integrated (Post-Hackathon)
23
+ **Issue:** [#73](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues/73)
24
+ **Spec:** [SPEC_08_INTEGRATE_MEMORY_LAYER.md](../specs/SPEC_08_INTEGRATE_MEMORY_LAYER.md)
25
+
26
+ **Problem:** Structured memory (hypotheses, conflicts) is isolated in "God Mode" only.
27
+ **Solution:** Extract memory into shared service, integrate into Simple and Advanced modes.
28
+ **Status:** Spec written. Blocked until post-hackathon.
29
 
30
  ### P3 - Ephemeral Memory (No Persistence)
31
  **File:** `P3_ARCHITECTURAL_GAP_EPHEMERAL_MEMORY.md`
docs/specs/SPEC_08_INTEGRATE_MEMORY_LAYER.md ADDED
@@ -0,0 +1,286 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # SPEC 08: Integrate Memory Layer into All Modes
2
+
3
+ **Status:** APPROVED
4
+ **Priority:** P1 (Post-Hackathon)
5
+ **Author:** Architecture Team
6
+ **Date:** 2025-11-29
7
+ **Depends On:** SPEC_07 (LangGraph Memory - IMPLEMENTED)
8
+ **Related Issue:** #73
9
+
10
+ ---
11
+
12
+ ## 1. Executive Summary
13
+
14
+ Integrate the structured memory layer (built in SPEC_07 as "God Mode") into Simple and Advanced modes. Remove the separate "God Mode" - memory becomes a shared capability, not a separate mode.
15
+
16
+ **Before (current - accidental):**
17
+ ```
18
+ Simple Mode β†’ No memory
19
+ Advanced Mode β†’ Chat-based memory
20
+ God Mode β†’ Structured memory ← ISOLATED
21
+ ```
22
+
23
+ **After (target):**
24
+ ```
25
+ Simple Mode β†’ Structured memory βœ“
26
+ Advanced Mode β†’ Structured memory βœ“
27
+ (God Mode removed from UI)
28
+ ```
29
+
30
+ ---
31
+
32
+ ## 2. What SPEC_07 Built (Already Done)
33
+
34
+ | Component | File | Status |
35
+ |-----------|------|--------|
36
+ | `ResearchState` TypedDict | `src/agents/graph/state.py` | βœ… Done |
37
+ | `Hypothesis` model | `src/agents/graph/state.py` | βœ… Done |
38
+ | `Conflict` model | `src/agents/graph/state.py` | βœ… Done |
39
+ | `EmbeddingService` | `src/services/embeddings.py` | βœ… Done |
40
+ | Hypothesis conversion | `src/agents/graph/nodes.py` | βœ… Done |
41
+
42
+ **This is the memory layer. It works. We just need to wire it into Simple and Advanced modes.**
43
+
44
+ ---
45
+
46
+ ## 3. Integration Plan
47
+
48
+ ### Phase 1: Create Shared Memory Service
49
+
50
+ Extract the memory logic from LangGraph nodes into a standalone service.
51
+
52
+ **New File:** `src/services/research_memory.py`
53
+
54
+ ```python
55
+ """Shared research memory layer for all orchestration modes."""
56
+
57
+ from dataclasses import dataclass, field
58
+ from typing import Literal
59
+
60
+ from src.agents.graph.state import Conflict, Hypothesis
61
+ from src.services.embeddings import EmbeddingService
62
+ from src.utils.models import Evidence
63
+
64
+
65
+ @dataclass
66
+ class ResearchMemory:
67
+ """Shared cognitive state for research workflows.
68
+
69
+ This is the memory layer that ALL modes use.
70
+ Built from SPEC_07, now extracted for integration.
71
+ """
72
+
73
+ query: str
74
+ hypotheses: list[Hypothesis] = field(default_factory=list)
75
+ conflicts: list[Conflict] = field(default_factory=list)
76
+ evidence_ids: list[str] = field(default_factory=list)
77
+ iteration_count: int = 0
78
+
79
+ # Injected services
80
+ _embedding_service: EmbeddingService | None = None
81
+
82
+ def __post_init__(self):
83
+ if self._embedding_service is None:
84
+ self._embedding_service = EmbeddingService()
85
+
86
+ async def store_evidence(self, evidence: list[Evidence]) -> list[str]:
87
+ """Store evidence and return new IDs (deduped)."""
88
+ if not self._embedding_service:
89
+ return []
90
+
91
+ unique = await self._embedding_service.deduplicate(evidence)
92
+ new_ids = []
93
+
94
+ for ev in unique:
95
+ ev_id = ev.citation.url
96
+ await self._embedding_service.add_evidence(
97
+ evidence_id=ev_id,
98
+ content=ev.content,
99
+ metadata={
100
+ "source": ev.citation.source,
101
+ "title": ev.citation.title,
102
+ "date": ev.citation.date,
103
+ "authors": ",".join(ev.citation.authors or []),
104
+ "url": ev.citation.url,
105
+ },
106
+ )
107
+ new_ids.append(ev_id)
108
+
109
+ self.evidence_ids.extend(new_ids)
110
+ return new_ids
111
+
112
+ async def get_relevant_evidence(self, n: int = 20) -> list[Evidence]:
113
+ """Retrieve relevant evidence for current query."""
114
+ if not self._embedding_service:
115
+ return []
116
+ return await self._embedding_service.search_similar(self.query, n_results=n)
117
+
118
+ def add_hypothesis(self, hypothesis: Hypothesis) -> None:
119
+ """Add a hypothesis to tracking."""
120
+ self.hypotheses.append(hypothesis)
121
+
122
+ def add_conflict(self, conflict: Conflict) -> None:
123
+ """Add a detected conflict."""
124
+ self.conflicts.append(conflict)
125
+
126
+ def get_open_conflicts(self) -> list[Conflict]:
127
+ """Get unresolved conflicts."""
128
+ return [c for c in self.conflicts if c.status == "open"]
129
+
130
+ def get_confirmed_hypotheses(self) -> list[Hypothesis]:
131
+ """Get high-confidence hypotheses."""
132
+ return [h for h in self.hypotheses if h.confidence > 0.8]
133
+ ```
134
+
135
+ ### Phase 2: Integrate into Simple Mode
136
+
137
+ **File:** `src/orchestrators/simple.py`
138
+
139
+ ```python
140
+ # Add to __init__
141
+ from src.services.research_memory import ResearchMemory
142
+
143
+ class Orchestrator:
144
+ def __init__(self, ...):
145
+ ...
146
+ self._memory: ResearchMemory | None = None
147
+
148
+ async def run(self, query: str) -> AsyncGenerator[AgentEvent, None]:
149
+ # Initialize memory for this run
150
+ self._memory = ResearchMemory(query=query)
151
+
152
+ # In search phase:
153
+ new_ids = await self._memory.store_evidence(search_results.evidence)
154
+
155
+ # In judge phase:
156
+ relevant = await self._memory.get_relevant_evidence(n=30)
157
+ # ... existing judge logic, but now with memory context
158
+
159
+ # Track hypotheses from judge assessment
160
+ for h in assessment.details.drug_candidates:
161
+ self._memory.add_hypothesis(Hypothesis(
162
+ id=h,
163
+ statement=f"{h} identified as candidate",
164
+ status="proposed",
165
+ confidence=assessment.confidence,
166
+ ))
167
+ ```
168
+
169
+ ### Phase 3: Integrate into Advanced Mode
170
+
171
+ **File:** `src/orchestrators/advanced.py`
172
+
173
+ ```python
174
+ # Same pattern - inject ResearchMemory
175
+ # Agents read/write to shared memory instead of chat history
176
+ ```
177
+
178
+ ### Phase 4: Remove God Mode from UI
179
+
180
+ **File:** `src/app.py`
181
+
182
+ ```python
183
+ # Before
184
+ mode = gr.Radio(
185
+ choices=["simple", "magentic", "god"],
186
+ ...
187
+ )
188
+
189
+ # After
190
+ mode = gr.Radio(
191
+ choices=["simple", "magentic"],
192
+ ...
193
+ )
194
+ # Memory is always enabled, not a mode choice
195
+ ```
196
+
197
+ **File:** `src/orchestrators/factory.py`
198
+
199
+ ```python
200
+ # Remove "god" and "langgraph" mode handling
201
+ # Keep LangGraphOrchestrator code for reference/future use
202
+ ```
203
+
204
+ ---
205
+
206
+ ## 4. What Stays, What Goes
207
+
208
+ | Component | Action |
209
+ |-----------|--------|
210
+ | `src/agents/graph/state.py` | βœ… KEEP - Hypothesis/Conflict models |
211
+ | `src/agents/graph/nodes.py` | ⚠️ EXTRACT - Move memory logic to service |
212
+ | `src/agents/graph/workflow.py` | πŸ“¦ ARCHIVE - LangGraph routing (optional) |
213
+ | `src/orchestrators/langgraph_orchestrator.py` | πŸ“¦ ARCHIVE - Not needed if memory integrated |
214
+ | `src/services/research_memory.py` | ✨ NEW - Shared memory service |
215
+
216
+ ---
217
+
218
+ ## 5. Files to Modify
219
+
220
+ | File | Change |
221
+ |------|--------|
222
+ | `src/services/research_memory.py` | NEW - Extract from nodes.py |
223
+ | `src/orchestrators/simple.py` | Add memory integration |
224
+ | `src/orchestrators/advanced.py` | Add memory integration |
225
+ | `src/orchestrators/factory.py` | Remove "god" mode |
226
+ | `src/app.py` | Remove God Mode from dropdown |
227
+ | `tests/unit/services/test_research_memory.py` | NEW - Test memory service |
228
+
229
+ ---
230
+
231
+ ## 6. Acceptance Criteria
232
+
233
+ - [ ] `ResearchMemory` service extracted and tested
234
+ - [ ] Simple mode uses `ResearchMemory` for evidence storage
235
+ - [ ] Simple mode tracks hypotheses from judge assessments
236
+ - [ ] Advanced mode uses `ResearchMemory` (shared state)
237
+ - [ ] "God Mode" removed from UI
238
+ - [ ] All existing tests pass
239
+ - [ ] New tests for memory integration
240
+
241
+ ---
242
+
243
+ ## 7. Why This is the Right Pattern
244
+
245
+ ```
246
+ Iterative Development:
247
+
248
+ 1. Build in isolation βœ… (SPEC_07 - God Mode)
249
+ - Test without breaking existing code
250
+ - Verify the concept works
251
+
252
+ 2. Ship isolated feature βœ… (PR #72)
253
+ - Get it into main
254
+ - Real users can test it
255
+
256
+ 3. Integrate into stack πŸ”œ (This spec)
257
+ - Wire into existing modes
258
+ - Remove scaffolding
259
+
260
+ 4. Clean up πŸ”œ
261
+ - Delete God Mode UI
262
+ - Archive LangGraph orchestrator
263
+ ```
264
+
265
+ **You shipped the hard part. Now it's just plumbing.**
266
+
267
+ ---
268
+
269
+ ## 8. Time Estimate
270
+
271
+ | Phase | Effort |
272
+ |-------|--------|
273
+ | Phase 1: Extract memory service | 2 hours |
274
+ | Phase 2: Simple mode integration | 2 hours |
275
+ | Phase 3: Advanced mode integration | 2 hours |
276
+ | Phase 4: UI cleanup | 30 mins |
277
+ | Testing | 1 hour |
278
+ | **Total** | **~8 hours** |
279
+
280
+ ---
281
+
282
+ ## 9. References
283
+
284
+ - SPEC_07: LangGraph Memory Architecture (implemented)
285
+ - PR #72: God Mode implementation
286
+ - Issue #73: Architectural refactor tracking