feat(memory): Migrate DISCOVERIES.md references to Kuzu memory backend (#1961)

rysweet · web-flow · commit 1a89afdea5a0 · 2026-01-17T13:06:25.000-08:00
All CI checks passing. Migrates DISCOVERIES.md to Kuzu memory backend. - 114 lines discoveries.py adapter - 251 lines comprehensive tests (11 passing) - 14 documentation files updated - Graceful fallback when memory unavailable Closes #1959
diff --git a/.claude/agents/amplihack/core/reviewer.md b/.claude/agents/amplihack/core/reviewer.md
@@ -146,7 +146,7 @@ Fix: [Minimal solution]
 - Implement minimal solution
 - Add regression test
 - Document the issue
-- Update DISCOVERIES.md if novel
+- Store discovery in memory if novel
 
 ## Review Output Format
 
@@ -324,7 +324,7 @@ gh pr comment 123 --body "LGTM! All issues addressed"
 - **Minimal changes**: Fix only what's broken
 - **Root cause**: Address the cause, not symptoms
 - **Add tests**: Prevent regression
-- **Document**: Update DISCOVERIES.md for novel issues
+- **Document**: Store discoveries in memory for novel issues
 - **Simplify**: Can the fix make things simpler?
 
 ## Remember
diff --git a/.claude/agents/amplihack/specialized/amplifier-cli-architect.md b/.claude/agents/amplihack/specialized/amplifier-cli-architect.md
@@ -440,7 +440,7 @@ async def coordinate_agents(task: str) -> Dict:
 - **Workflow**: Map decisions to multi-step workflow
 - **Priorities**: Explicit requirements > implicit preferences > philosophy > defaults
 - **Execution**: Support parallel execution where decisions are independent
-- **Knowledge**: Update DISCOVERIES.md with learnings
+- **Knowledge**: Store learnings in memory via discoveries adapter
 
 ## Success Metrics
 
diff --git a/.claude/agents/amplihack/specialized/fix-agent.md b/.claude/agents/amplihack/specialized/fix-agent.md
@@ -200,7 +200,7 @@ Execute all 22 steps of DEFAULT_WORKFLOW:
 
 **Step 21: Documentation Updates**
 
-- Update DISCOVERIES.md if needed
+- Store discovery in memory if needed
 - Document fix pattern for future reference
 - Update related documentation
 
diff --git a/.claude/agents/amplihack/workflows/amplihack-improvement-workflow.md b/.claude/agents/amplihack/workflows/amplihack-improvement-workflow.md
@@ -145,7 +145,7 @@ Redundancy Check:
 - [ ] No security warnings
 - [ ] No philosophy violations
 - [ ] Documentation updated
-- [ ] DISCOVERIES.md updated if novel
+- [ ] Discoveries stored in memory if novel
 
 ## Complexity Justification
 
@@ -301,9 +301,9 @@ security_issues: [count]
 time_to_complete: [duration]
 ```
 
-### Update DISCOVERIES.md
+### Store Discoveries in Memory
 
-When patterns emerge:
+When patterns emerge, use `store_discovery()` from `amplihack.memory.discoveries`:
 
 ```markdown
 ## Improvement Pattern Discovered
diff --git a/.claude/skills/cascade-workflow/SKILL.md b/.claude/skills/cascade-workflow/SKILL.md
@@ -261,7 +261,7 @@ What's Missing:
 - Adjust timeouts based on success rates
 - Improve secondary approaches if frequently used
 - Update tertiary if inadequate
-- Document learnings in `.claude/context/DISCOVERIES.md`
+- Store learnings in memory using `store_discovery()` from `amplihack.memory.discoveries`
 
 **Optimization Criteria:**
 
diff --git a/.claude/skills/debate-workflow/SKILL.md b/.claude/skills/debate-workflow/SKILL.md
@@ -349,7 +349,7 @@ Counter: [Additional evidence or reasoning]
 - Document full debate transcript
 - Include all perspective arguments
 - Record synthesis and final decision
-- Add to `.claude/context/DISCOVERIES.md`
+- Store in memory using `store_discovery()` from `amplihack.memory.discoveries`
 - Update relevant architecture docs
 
 **Decision Record Template:**
diff --git a/.claude/skills/investigation-workflow/SKILL.md b/.claude/skills/investigation-workflow/SKILL.md
@@ -250,7 +250,7 @@ Verification: Examine reflection logs, trace message processing
 
 **Tasks**:
 
-- **Update .claude/context/DISCOVERIES.md** with key insights
+- **Store discoveries in memory** using `store_discovery()` from `amplihack.memory.discoveries`
 - **Update .claude/context/PATTERNS.md** if reusable patterns found
 - Create or update relevant documentation files
 - Add inline code comments for critical understanding
@@ -275,14 +275,14 @@ Verification: Examine reflection logs, trace message processing
 
 **Success Criteria**:
 
-- DISCOVERIES.md updated with investigation results
+- Discoveries stored in memory for future reference
 - Relevant documentation files updated
 - Knowledge is discoverable by future investigators
 - No information loss
 
 **Deliverables**:
 
-- Updated DISCOVERIES.md
+- Discoveries stored in memory
 - Updated PATTERNS.md (if applicable)
 - Updated project documentation
 - Optional: GitHub issues for improvements
@@ -294,7 +294,7 @@ Verification: Examine reflection logs, trace message processing
 
 1. **Resume at Step 4** (Research and Design) with the knowledge gained from investigation
 2. **Or resume at Step 5** (Implement the Solution) if the investigation already provided clear design guidance
-3. **Use investigation findings** from DISCOVERIES.md and session logs to inform design decisions
+3. **Use investigation findings** from memory (via `get_recent_discoveries()`) and session logs to inform design decisions
 
 **Example Hybrid Workflow**:
 
@@ -304,7 +304,7 @@ User: "/ultrathink investigate how authentication works, then add OAuth support"
 Phase 1: Investigation
 → Run INVESTIGATION_WORKFLOW.md (6 phases)
 → Complete understanding of existing auth system
-→ Document findings in DISCOVERIES.md
+→ Store findings in memory via discoveries adapter
 
 Phase 2: Development
 → Transition to DEFAULT_WORKFLOW.md
@@ -407,7 +407,7 @@ Track these metrics to validate workflow effectiveness:
 
 - **Message Count**: Target 30-40% reduction vs. ad-hoc (to be validated)
 - **Investigation Time**: Track time to completion
-- **Knowledge Reuse**: How often DISCOVERIES.md prevents repeat work
+- **Knowledge Reuse**: How often memory retrieval prevents repeat work
 - **Completeness**: Percentage of investigations with full documentation
 - **User Satisfaction**: Clear understanding achieved
 
@@ -416,7 +416,7 @@ Track these metrics to validate workflow effectiveness:
 - **Scope first, explore second** - Define boundaries before diving in
 - **Parallel exploration is key** - Deploy multiple agents simultaneously in Phase 3
 - **Verify understanding** - Test your hypotheses in Phase 4
-- **Capture knowledge** - Always update DISCOVERIES.md in Phase 6
+- **Capture knowledge** - Always store discoveries in memory in Phase 6
 - **This workflow optimizes for understanding, not implementation**
 
 When in doubt about investigation vs. development:
diff --git a/.claude/skills/knowledge-extractor/SKILL.md b/.claude/skills/knowledge-extractor/SKILL.md
@@ -4,8 +4,8 @@ version: 1.0.0
 description: |
   Extracts key learnings from conversations, debugging sessions, and failed attempts.
   Use at session end or after solving complex problems to capture insights.
-  Automatically suggests updates to: DISCOVERIES.md (learnings), PATTERNS.md (reusable solutions), new agent creation (repeated workflows).
-  Ensures knowledge persists across sessions.
+  Stores discoveries in memory (via amplihack.memory.discoveries), suggests PATTERNS.md updates, and recommends new agent creation.
+  Ensures knowledge persists across sessions via Kuzu memory backend.
 ---
 
 # Knowledge Extractor Skill
@@ -251,7 +251,7 @@ Extract and structure knowledge:
 Place knowledge in correct locations:
 
 ```
-DISCOVERIES.md → New discovery at end of file
+Memory → Store discovery using store_discovery() from amplihack.memory.discoveries
 PATTERNS.md → New pattern in appropriate section
 Agent → Create in .claude/agents/amplihack/specialized/
 ```
@@ -426,12 +426,12 @@ Before finalizing an extraction, verify:
 
 ## Integration with System
 
-### DISCOVERIES.md Lifecycle
+### Discovery Memory Lifecycle
 
-1. **Extraction**: Added to DISCOVERIES.md during session
-2. **Visibility**: Immediately available to all agents
-3. **Action**: Agents can reference when solving similar problems
-4. **Prevention**: Prevents repeating same mistakes
+1. **Extraction**: Stored in memory via `store_discovery()` during session
+2. **Visibility**: Retrieved by `get_recent_discoveries()` at session start
+3. **Action**: Agents can query memory when solving similar problems
+4. **Prevention**: Prevents repeating same mistakes across sessions
 5. **Evolution**: Updated when better solution found
 
 ### PATTERNS.md Lifecycle
@@ -455,7 +455,7 @@ Before finalizing an extraction, verify:
 ### Impact 1: Prevent Wasted Debugging Time
 
 **Without knowledge extraction**: Repeat same 45-minute debugging process
-**With extraction**: Reference DISCOVERIES.md, fix in 10 minutes
+**With extraction**: Retrieve from memory, fix in 10 minutes
 
 ### Impact 2: Faster Solution Discovery
 
diff --git a/.claude/skills/n-version-workflow/SKILL.md b/.claude/skills/n-version-workflow/SKILL.md
@@ -195,7 +195,7 @@ Selection Criteria Applied:
 - Document all N implementations generated
 - Explain selection rationale in detail
 - Capture insights from rejected versions
-- Update `.claude/context/DISCOVERIES.md` with patterns learned
+- Store patterns learned in memory using `store_discovery()` from `amplihack.memory.discoveries`
 - Include comparison matrix for future reference
 
 ## Trade-Offs
diff --git a/.claude/skills/philosophy-compliance-workflow/SKILL.md b/.claude/skills/philosophy-compliance-workflow/SKILL.md
@@ -396,7 +396,7 @@ A successful philosophy review:
 
 - `.claude/runtime/logs/<session>/philosophy_review_<timestamp>.md`
 - Link in commit message if fixes applied
-- Update `.claude/context/DISCOVERIES.md` with patterns learned
+- Store patterns learned in memory using `store_discovery()` from `amplihack.memory.discoveries`
 
 ## Remember
 
diff --git a/.claude/tools/amplihack/hooks/session_start.py b/.claude/tools/amplihack/hooks/session_start.py
@@ -196,10 +196,24 @@ def process(self, input_data: dict[str, Any]) -> dict[str, Any]:
         context_parts.append("This is the Microsoft Hackathon 2025 Agentic Coding project.")
         context_parts.append("Focus on building AI-powered development tools.")
 
-        # Check for recent discoveries
-        discoveries_file = self.project_root / ".claude" / "context" / "DISCOVERIES.md"
-        if discoveries_file.exists():
-            context_parts.append("\n## Recent Learnings")
+        # Check for recent discoveries from memory
+        context_parts.append("\n## Recent Learnings")
+        try:
+            from amplihack.memory.discoveries import get_recent_discoveries
+
+            recent_discoveries = get_recent_discoveries(days=30, limit=5)
+            if recent_discoveries:
+                context_parts.append(
+                    f"Found {len(recent_discoveries)} recent discoveries in memory:"
+                )
+                for disc in recent_discoveries:
+                    summary = disc.get("summary", "No summary")
+                    category = disc.get("category", "uncategorized")
+                    context_parts.append(f"- [{category}] {summary}")
+            else:
+                context_parts.append("Check .claude/context/DISCOVERIES.md for recent insights.")
+        except ImportError:
+            # Fallback if memory module not available
             context_parts.append("Check .claude/context/DISCOVERIES.md for recent insights.")
 
         # Simplified preference file resolution
@@ -318,8 +332,7 @@ def _select_strategy(self):
 
         if launcher_type == "copilot":
             return CopilotStrategy(self.project_root, self.log)
-        else:
-            return ClaudeStrategy(self.project_root, self.log)
+        return ClaudeStrategy(self.project_root, self.log)
 
     def _check_version_mismatch(self) -> None:
         """Check for version mismatch and offer to update.
diff --git a/.claude/workflow/INVESTIGATION_WORKFLOW.md b/.claude/workflow/INVESTIGATION_WORKFLOW.md
@@ -290,7 +290,7 @@ Verification: Examine reflection logs, trace message processing
 
 **Tasks:**
 
-- [ ] **Update .claude/context/DISCOVERIES.md** with key insights
+- [ ] **Store discoveries in memory** using `store_discovery()` from `amplihack.memory.discoveries`
 - [ ] **Update .claude/context/PATTERNS.md** if reusable patterns found
 - [ ] Create or update relevant documentation files
 - [ ] Add inline code comments for critical understanding
@@ -315,14 +315,14 @@ Verification: Examine reflection logs, trace message processing
 
 **Success Criteria:**
 
-- DISCOVERIES.md updated with investigation results
+- Discoveries stored in memory for future reference
 - Relevant documentation files updated
 - Knowledge is discoverable by future investigators
 - No information loss
 
 **Deliverables:**
 
-- Updated DISCOVERIES.md
+- Discoveries stored in memory
 - Updated PATTERNS.md (if applicable)
 - Updated project documentation
 - Optional: GitHub issues for improvements
@@ -334,7 +334,7 @@ Verification: Examine reflection logs, trace message processing
 
 1. **Resume at Step 4** (Research and Design) with the knowledge gained from investigation
 2. **Or resume at Step 5** (Implement the Solution) if the investigation already provided clear design guidance
-3. **Use investigation findings** from DISCOVERIES.md and session logs to inform design decisions
+3. **Use investigation findings** from memory (via `get_recent_discoveries()`) and session logs to inform design decisions
 
 **Example Hybrid Workflow:**
 
@@ -344,7 +344,7 @@ User: "/ultrathink investigate how authentication works, then add OAuth support"
 Phase 1: Investigation
 → Run INVESTIGATION_WORKFLOW.md (6 phases)
 → Complete understanding of existing auth system
-→ Document findings in DISCOVERIES.md
+→ Store findings in memory via discoveries adapter
 
 Phase 2: Development
 → Transition to DEFAULT_WORKFLOW.md
@@ -451,7 +451,7 @@ Track these metrics to validate workflow effectiveness:
 
 - **Message Count**: Target 30-40% reduction vs. ad-hoc (to be validated)
 - **Investigation Time**: Track time to completion
-- **Knowledge Reuse**: How often DISCOVERIES.md prevents repeat work
+- **Knowledge Reuse**: How often memory retrieval prevents repeat work
 - **Completeness**: Percentage of investigations with full documentation
 - **User Satisfaction**: Clear understanding achieved
 
@@ -460,7 +460,7 @@ Track these metrics to validate workflow effectiveness:
 - **Scope first, explore second** - Define boundaries before diving in
 - **Parallel exploration is key** - Deploy multiple agents simultaneously in Phase 3
 - **Verify understanding** - Test your hypotheses in Phase 4
-- **Capture knowledge** - Always update DISCOVERIES.md in Phase 6
+- **Capture knowledge** - Always store discoveries in memory in Phase 6
 - **This workflow optimizes for understanding, not implementation**
 
 When in doubt about investigation vs. development:
diff --git a/.claude/workflow/N_VERSION_WORKFLOW.md b/.claude/workflow/N_VERSION_WORKFLOW.md
@@ -271,7 +271,7 @@ See: n_version_analysis.md for full comparison matrix
 - [ ] Document all N implementations generated
 - [ ] Explain selection rationale in detail
 - [ ] Capture insights from rejected versions
-- [ ] Update `.claude/context/DISCOVERIES.md` with patterns learned
+- [ ] Store patterns learned in memory using `store_discovery()` from `amplihack.memory.discoveries`
 - [ ] Include comparison matrix for future reference
 
 **Analysis Document Structure:**
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -113,9 +113,8 @@ Following: .claude/workflow/[WORKFLOW_NAME].md
   judgement, and only stop to ask if really necessary or explicitly instructed
   to do so.
 - **Check discoveries before problem-solving**: Before solving complex problems,
-  check `@docs/DISCOVERIES.md` for known issues and solutions
-- **Document learnings**: Update .claude/context/DISCOVERIES.md with new
-  insights
+  retrieve recent discoveries from memory using `get_recent_discoveries()` from `amplihack.memory.discoveries`
+- **Document learnings**: Store discoveries in memory using `store_discovery()` from `amplihack.memory.discoveries`
 - **Session Logs**: All interactions MUST be logged in
   .claude/runtime/logs/<session_id> where <session_id> is a unique identifier
   for the session based on the timestamp.
@@ -843,14 +842,14 @@ After code changes:
 1. Run tests if available
 2. Check philosophy compliance
 3. Verify module boundaries
-4. Update .claude/context/DISCOVERIES.md with learnings
+4. Store learnings in memory via discoveries adapter
 
 ## Self-Improvement
 
 The system should continuously improve:
 
 - Track patterns in `.claude/context/PATTERNS.md`
-- Document discoveries in `.claude/context/DISCOVERIES.md`
+- Store discoveries in memory for cross-session persistence
 - Update agent definitions as needed
 - Create new agents for repeated tasks
 
diff --git a/src/amplihack/memory/discoveries.py b/src/amplihack/memory/discoveries.py
diff --git a/tests/memory/test_discoveries_adapter.py b/tests/memory/test_discoveries_adapter.py
