[2026NewYearChallenge] feat: Add Memory Reasoning Engine with derived knowledge inference #250
Description
What this PR does
Adds a Memory Reasoning Engine (MRE) that transforms MemU from a retrieval system into a reasoning system.
The core insight: Memory should not be static. Memory should produce new memory.
Current State vs Enhancement
| Capability | Current MemU | With MRE |
|---|---|---|
| Memory access | Retrieve by similarity | Reason over relationships |
| Output | Stored memories | Stored + derived knowledge |
| Agent behavior | Reactive (answer when asked) | Reflective (infer before asked) |
The Reasoning Loop
RETRIEVE → TRAVERSE → FILTER → SCORE → INFER → WRITE BACK
- RETRIEVE - Get candidate memories matching query constraints
- TRAVERSE - Walk knowledge graph relationships (requires feat: Add Knowledge Graph with entity extraction and graph traversal #249)
- FILTER - Apply type, time range, confidence thresholds
- SCORE - Rank by relevance + tool success rates (requires feat: Add Tool Memory type with specialized metadata and statistics #247)
- INFER - LLM-assisted conclusion generation
- WRITE BACK - Store derived memories with provenance
Key Components
ReasoningQuery DSL - Structured queries with constraints:
query = ReasoningQuery(
goal="Who can help with database optimization?",
constraints=ReasoningConstraints(
entity_types=["Person"],
memory_types=["knowledge", "tool"],
relationships=["works_on", "expert_in"],
time_range_days=30,
require_tool_success=True
),
reasoning_depth=2
)
DerivedMemory - Machine-generated knowledge with full provenance:
DerivedMemory(
content="John is the best database expert",
inference_type="deduction", # deduction | induction | summarization | analogy
source_memory_ids=["mem_1", "mem_2", "mem_3"],
confidence_score=0.85,
expires_at=datetime(2026, 2, 1) # Optional TTL for time-sensitive conclusions
)
Self-Consistency Verification - Run inference N times with different seeds:
Consistent results → reinforce confidence
Inconsistent results → weaken confidence
Prevents hallucination from becoming "memory"
Example: Agent Self-Improvement
# Agent asks: "Who should I contact about backend performance?"
trace = await reasoner.reason(ReasoningQuery(
goal="Who should I contact about backend performance?",
constraints=ReasoningConstraints(
entity_types=["Person"],
relationships=["expert_in", "worked_on"]
)
))
# System:
# 1. Retrieves memories about people, skills, projects
# 2. Traverses graph: Person → skills → projects → outcomes
# 3. Scores by tool success rates (who actually delivered?)
# 4. Infers: "John has 90% success rate on DB tasks, worked on backend"
# 5. Writes DerivedMemory: "John is the best backend contact"
# Next time agent needs backend help → instant answer, no re-reasoning
Why This Matters
This is the difference between:
Memory as storage - "Here's what I remember"
Memory as cognition - "Here's what I concluded from what I remember"
Agents with MRE don't just recall - they learn, infer, and build knowledge over time.
Dependencies
Builds on Knowledge Graph (#249) for relationship traversal
Builds on Tool Memory (#247) for success rate scoring
Works standalone with reduced capability if dependencies not present
Files Added
File Purpose
src/memu/reasoning/__init__.py Module exports
src/memu/reasoning/query_dsl.py ReasoningQuery, ReasoningConstraints, ReasoningTrace
src/memu/reasoning/derived_memory.py DerivedMemory, DerivedMemoryStore
src/memu/reasoning/memory_reasoner.py Core MemoryReasoner class
src/memu/reasoning/prompts.py LLM prompts for inference
tests/test_memory_reasoner.py 29 unit tests
Tests
All 29 tests passing covering:
Query DSL validation
Reasoning loop execution
Derived memory creation and deduplication
Confidence reinforcement/weakening
Expiration and pruning
Graph traversal integration
Tool stats integration