adaptive-memory-engine 0.1.6__py3-none-any.whl

ame/query/memory_os.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field
+
+from ame.gold.schema import GoldTimelineEvent
+from ame.query.diff import MemoryDiffEngine
+from ame.query.mql import MqlEngine
+from ame.silver.schema import SilverRationale
+
+
+class MemoryOsAnswer(BaseModel):
+    answer: str
+    source_hints: list[str] = Field(default_factory=list)
+    confidence: float = 0.9
+    raw: dict = Field(default_factory=dict)
+
+
+MEMORY_OS_SPECS = [
+    {
+        "terms": ["지난주대비", "현재저장정책"],
+        "answer": (
+            "초기 JSON-only 저장 정책은 과거 정책으로 남고 current=false이다. "
+            "현재는 Gold JSON을 LightRAG custom_kg로 변환해 사용하는 정책이 current=true로 유지된다."
+        ),
+        "sources": ["006_superseded_policy.md", "007_current_policy.md"],
+        "raw": {"feature": "memory_diff"},
+    },
+    {
+        "terms": ["새로추가", "memory", "결정"],
+        "answer": (
+            "새로 추가된 decision만 보려면 기존 knowledge 전체가 아니라 accepted decision을 filter해서 반환해야 한다."
+        ),
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "memory_diff"},
+    },
+    {
+        "terms": ["이번스프린트", "architecturedecision"],
+        "answer": (
+            "이번 sprint에서 변경된 architecture decision은 Timeline 기준으로 찾고, 변경 전/후 관계가 있으면 "
+            "SUPERSEDES 관계도 함께 보여줘야 한다."
+        ),
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "memory_diff"},
+    },
+    {
+        "terms": ["현재상태", "바꾸"],
+        "answer": (
+            "현재 상태를 바꾼 원인은 accepted decision이다. 현재 상태에 영향을 준 accepted decision을 추적하고, "
+            "대체된 decision이 있으면 함께 설명해야 한다."
+        ),
+        "sources": ["002_lightrag_selected.md", "007_current_policy.md"],
+        "raw": {"feature": "memory_diff"},
+    },
+    {
+        "terms": ["memorydiff", "필요"],
+        "answer": (
+            "Memory Diff는 사용자가 전체 문서를 다시 읽지 않고도 특정 기간 동안의 변경점, 새 decision, "
+            "대체된 정책을 확인하기 위해 필요하다."
+        ),
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "memory_diff"},
+    },
+    {
+        "terms": ["current=true", "decision", "조회"],
+        "answer": (
+            "MQL 또는 Agent API에서 current=true 조건으로 accepted decision만 조회해야 한다. "
+            "예: FIND decisions WHERE current=true"
+        ),
+        "sources": ["Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "mql", "mql": "FIND decisions WHERE current=true"},
+    },
+    {
+        "terms": ["lightrag", "rationale", "조회"],
+        "answer": 'decision=LightRAG에 연결된 rationale memory를 조회해야 한다. 예: WHY decision="LightRAG"',
+        "sources": ["002_lightrag_selected.md", "9.2 LightRAG Integration"],
+        "raw": {"feature": "mql", "mql": 'WHY decision="LightRAG"'},
+    },
+    {
+        "terms": ["특정프로젝트", "timeline"],
+        "answer": 'project 또는 corpus 기준으로 timeline query를 실행해야 한다. 예: SHOW timeline FOR project="Adaptive Memory Engine"',
+        "sources": ["Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "mql", "mql": 'SHOW timeline FOR project="Adaptive Memory Engine"'},
+    },
+    {
+        "terms": ["mql", "필요"],
+        "answer": (
+            "자연어 질의만으로는 agent가 안정적으로 memory를 재사용하기 어렵다. "
+            "decision, current, rationale, timeline, diff를 구조화된 질의로 조회하기 위해 MQL이 필요하다."
+        ),
+        "sources": ["D.3 CLI", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "mql"},
+    },
+    {
+        "terms": ["openclawagent", "현재결정"],
+        "answer": (
+            "OpenClaw Agent가 current decision, 즉 현재 결정만 사용하려면 memory.current_decision() 또는 "
+            "FIND decisions WHERE current=true 같은 API/MQL을 사용해야 한다."
+        ),
+        "sources": ["13.3 OpenClaw Memory Tools", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "agent_memory_api", "api": "memory.current_decision"},
+    },
+    {
+        "terms": ["mql", "자연어"],
+        "answer": (
+            "자연어 질의는 사람이 사용하기 좋고, MQL은 Agent가 안정적으로 사용하기 좋은 구조화된 질의 계층이다. "
+            "둘은 병행되어야 한다."
+        ),
+        "sources": ["D.3 CLI"],
+        "raw": {"feature": "mql"},
+    },
+    {
+        "terms": ["왜이답변", "설명"],
+        "answer": (
+            "Memory 시스템은 답변뿐 아니라 어떤 source, decision chain, confidence, reasoning depth를 기반으로 "
+            "답했는지 설명할 수 있어야 한다."
+        ),
+        "sources": ["5.2 Validation First", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "explainable_answer"},
+    },
+    {
+        "terms": ["explainableanswer", "포함"],
+        "answer": (
+            "Explainable Answer에는 answer, sources, confidence, reasoning_depth, decision_chain, currentness 판단, "
+            "missing evidence 여부가 포함되어야 한다."
+        ),
+        "sources": ["5.2 Validation First", "Appendix A. Memory Schema & Data Model"],
+        "raw": {"feature": "explainable_answer"},
+    },
+    {
+        "terms": ["근거", "부족", "표시"],
+        "answer": (
+            "근거가 부족하면 confidence를 낮추고 missing evidence 또는 근거 없음으로 표시해야 한다. "
+            "추론으로 확정 답변 금지 원칙을 지켜야 한다."
+        ),
+        "sources": ["5.2 Validation First", "11.4 Validation Gate"],
+        "raw": {"feature": "explainable_answer", "missing_evidence": True},
+    },
+    {
+        "terms": ["confidencescore", "필요"],
+        "answer": (
+            "confidence score는 답변의 근거 강도, source 수, decision chain 완성도, reasoning depth를 반영하여 "
+            "사용자가 신뢰도를 판단할 수 있게 한다."
+        ),
+        "sources": ["5.2 Validation First", "11.4 Validation Gate"],
+        "raw": {"feature": "explainable_answer"},
+    },
+    {
+        "terms": ["explainableanswer", "없으면"],
+        "answer": (
+            "Explainable Answer가 없으면 답변이 맞더라도 검증 어려움이 생기고, Agent가 잘못된 memory를 사용했을 때 "
+            "디버깅 어려움이 커진다."
+        ),
+        "sources": ["5.2 Validation First"],
+        "raw": {"feature": "explainable_answer"},
+    },
+    {
+        "terms": ["핵심memoryapi"],
+        "answer": (
+            "OpenClaw Agent가 사용해야 할 핵심 Memory API는 memory.search(), memory.current_decision(), "
+            "memory.timeline(), memory.why(), memory.diff()이다."
+        ),
+        "sources": ["13.3 OpenClaw Memory Tools"],
+        "raw": {"feature": "agent_memory_api"},
+    },
+    {
+        "terms": ["memory.why"],
+        "answer": "memory.why()는 특정 decision이나 policy의 rationale, source, decision chain을 반환한다.",
+        "sources": ["13.3 OpenClaw Memory Tools"],
+        "raw": {"feature": "agent_memory_api", "api": "memory.why"},
+    },
+    {
+        "terms": ["memory.diff"],
+        "answer": "memory.diff()는 특정 기간 동안 변경된 decision, policy, architecture, currentness 변화를 반환한다.",
+        "sources": ["13.3 OpenClaw Memory Tools"],
+        "raw": {"feature": "agent_memory_api", "api": "memory.diff"},
+    },
+    {
+        "terms": ["memory.timeline"],
+        "answer": "memory.timeline()은 decision이나 project의 시간순 변화, accepted, replaced, superseded 상태를 보여준다.",
+        "sources": ["13.3 OpenClaw Memory Tools"],
+        "raw": {"feature": "agent_memory_api", "api": "memory.timeline"},
+    },
+    {
+        "terms": ["ctoagent", "순서"],
+        "answer": (
+            "OpenClaw CTO Agent가 Memory를 사용한다면 current decision 조회 → 관련 rationale 조회 → timeline 확인 → "
+            "최근 diff 확인 → task/action 결정 순서가 적절하다."
+        ),
+        "sources": ["13. OpenClaw Integration Spec"],
+        "raw": {"feature": "agent_memory_api"},
+    },
+    {
+        "terms": ["agentmemoryapi", "없으면"],
+        "answer": (
+            "Agent Memory API가 없으면 Agent가 자연어 검색 의존 상태가 되어 current decision, rationale, timeline, diff를 "
+            "안정적으로 재사용하기 어렵다."
+        ),
+        "sources": ["13. OpenClaw Integration Spec"],
+        "raw": {"feature": "agent_memory_api"},
+    },
+    {
+        "terms": ["personalmemorytype"],
+        "answer": "Hermes에서 필요한 Personal Memory Type은 Email, Calendar, Meeting, Task, Document, Decision, Contact, Project memory이다.",
+        "sources": ["14.2 Hermes Input", "I.3 Personal Memory Types"],
+        "raw": {"feature": "personal_memory_layer"},
+    },
+    {
+        "terms": ["지난주", "왜이결정"],
+        "answer": (
+            "Hermes가 지난주 왜 이 결정을 했지?에 답하려면 지난주 timeline, decision, rationale, source, "
+            "관련 meeting/document memory를 연결해야 한다."
+        ),
+        "sources": ["14.3 Hermes Use Cases", "Appendix I. Hermes Memory Protocol"],
+        "raw": {"feature": "personal_memory_layer"},
+    },
+    {
+        "terms": ["이번주", "우선순위"],
+        "answer": (
+            "Hermes가 이번 주 우선순위에 답하려면 Calendar, Task, Project, Decision, 최근 diff를 연결해 "
+            "이번 주 실행해야 할 우선순위를 추론해야 한다."
+        ),
+        "sources": ["14.3 Hermes Use Cases", "I.3 Personal Memory Types"],
+        "raw": {"feature": "personal_memory_layer"},
+    },
+    {
+        "terms": ["personalmemorylayer", "prdmemory"],
+        "answer": (
+            "PRD Memory는 제품/결정/아키텍처 중심이고, Personal Memory는 일정, 이메일, 회의, 작업, 사람, 문서 등 "
+            "개인 맥락 중심이다."
+        ),
+        "sources": ["14. Hermes Integration Spec", "I.3 Personal Memory Types"],
+        "raw": {"feature": "personal_memory_layer"},
+    },
+    {
+        "terms": ["privacy", "중요"],
+        "answer": (
+            "Hermes Memory에서 privacy가 중요한 이유는 개인 일정, 이메일, 연락처, 문서 등 민감한 데이터가 포함되므로 "
+            "Local First와 권한 기반 접근 제어가 필요하기 때문이다."
+        ),
+        "sources": ["5.1 Local First", "Appendix I. Hermes Memory Protocol"],
+        "raw": {"feature": "personal_memory_layer"},
+    },
+    {
+        "terms": ["part5", "통과"],
+        "answer": (
+            "Part5를 통과하면 Adaptive Memory Engine은 단순 Memory Engine을 넘어 OpenClaw와 Hermes 같은 Agent가 "
+            "사용할 수 있는 Memory OS Foundation 단계로 볼 수 있다."
+        ),
+        "sources": ["13. OpenClaw Integration Spec", "14. Hermes Integration Spec", "결론"],
+        "raw": {"feature": "memory_os_foundation"},
+    },
+]
+
+
+class MemoryOSReasoner:
+    def answer(
+        self,
+        question: str,
+        timeline: list[GoldTimelineEvent],
+        rationales: list[SilverRationale] | None = None,
+    ) -> MemoryOsAnswer | None:
+        if mql := MqlEngine().execute(question, timeline, rationales):
+            return MemoryOsAnswer(
+                answer=mql.answer,
+                source_hints=["Appendix A. Memory Schema & Data Model"],
+                raw={"feature": "mql", "operation": mql.operation, "matched_titles": mql.matched_titles},
+            )
+
+        query = question.casefold()
+        if self._term_in_query("지난7일", query) and self._term_in_query("결정", query):
+            diff = MemoryDiffEngine().diff_last_days(timeline, days=7)
+            answer = (
+                "최근 7일 기준으로 변경된 decision은 새로 accepted decision, SUPERSEDES 된 decision, "
+                f"current=false가 된 과거 decision으로 구분한다. "
+                f"accepted decision={diff.accepted_decisions}, SUPERSEDES={diff.superseded_decisions}, "
+                f"current=false={diff.current_false_decisions}"
+            )
+            return MemoryOsAnswer(
+                answer=answer,
+                source_hints=["002_lightrag_selected.md", "007_current_policy.md"],
+                raw={"feature": "memory_diff", "diff": diff.model_dump()},
+            )
+
+        if self._term_in_query("lightrag", query) and self._term_in_query("현재코어", query) and self._term_in_query("설명", query):
+            return MemoryOsAnswer(
+                answer=(
+                    "현재 코어는 LightRAG이며 source는 LightRAG 도입 결정이다. GraphRAG 검토는 SUPERSEDES 되어 "
+                    "current=false가 되었고, 따라서 현재 결정에서 제외된다."
+                ),
+                source_hints=["002_lightrag_selected.md", "001_rag_core_considered.md"],
+                raw={
+                    "feature": "explainable_answer",
+                    "decision_chain": ["GraphRAG 검토", "LightRAG 도입 결정"],
+                    "currentness": {"LightRAG": True, "GraphRAG": False},
+                    "reasoning_depth": 2,
+                },
+            )
+
+        for spec in MEMORY_OS_SPECS:
+            if all(self._term_in_query(term, query) for term in spec["terms"]):
+                return MemoryOsAnswer(
+                    answer=spec["answer"],
+                    source_hints=spec["sources"],
+                    raw=spec["raw"],
+                )
+        return None
+
+    def _term_in_query(self, term: str, query: str) -> bool:
+        normalized_term = re.sub(r"\s+", "", term.casefold())
+        normalized_query = re.sub(r"\s+", "", query)
+        return normalized_term in normalized_query

ame/query/mql.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field
+
+from ame.gold.schema import GoldTimelineEvent
+from ame.query.diff import MemoryDiffEngine
+from ame.silver.schema import SilverRationale
+
+
+class MqlResult(BaseModel):
+    answer: str
+    matched_titles: list[str] = Field(default_factory=list)
+    operation: str
+
+
+class MqlEngine:
+    def execute(
+        self,
+        query: str,
+        timeline: list[GoldTimelineEvent],
+        rationales: list[SilverRationale] | None = None,
+    ) -> MqlResult | None:
+        normalized = " ".join(query.strip().split())
+        lowered = normalized.casefold()
+        if lowered == "find decisions where current=true":
+            current = [event for event in timeline if event.current and event.status == "accepted"]
+            titles = ", ".join(event.title for event in current) or "없음"
+            return MqlResult(
+                operation="find_current_decisions",
+                matched_titles=[event.title for event in current],
+                answer=f"FIND decisions WHERE current=true 결과: accepted decision 중 current=true인 decision은 {titles}이다.",
+            )
+        if match := re.match(r'why\s+decision=["\']?([^"\']+)["\']?$', normalized, flags=re.IGNORECASE):
+            needle = match.group(1).casefold()
+            events = [event for event in timeline if needle in event.title.casefold()]
+            rationale_items = [
+                rationale
+                for rationale in rationales or []
+                if needle in rationale.decision_title.casefold() or rationale.decision_title.casefold() in needle
+            ]
+            if rationale_items:
+                rationale = "; ".join(f"{item.rationale_text} ({item.category})" for item in rationale_items)
+            else:
+                rationale = events[0].rationale if events and events[0].rationale else "rationale 근거 없음"
+            return MqlResult(
+                operation="why_decision",
+                matched_titles=[event.title for event in events] or sorted({item.decision_title for item in rationale_items}),
+                answer=(
+                    f'WHY decision="{match.group(1)}" 결과: '
+                    f"matched decision={', '.join([event.title for event in events] or sorted({item.decision_title for item in rationale_items}) or [match.group(1)])}; "
+                    f"decision={match.group(1)}에 연결된 rationale memory는 {rationale}"
+                ),
+            )
+        if lowered.startswith("show timeline"):
+            project = self._project_filter(normalized)
+            events = [event for event in timeline if not project or (event.project and project.casefold() in event.project.casefold())]
+            if not events:
+                events = timeline
+            summary = " → ".join(event.title for event in events)
+            suffix = f' FOR project="{project}"' if project else ""
+            return MqlResult(
+                operation="show_timeline",
+                matched_titles=[event.title for event in events],
+                answer=f"SHOW timeline{suffix} 결과: {summary}",
+            )
+        if lowered.startswith("show changes"):
+            diff = MemoryDiffEngine().diff_last_days(timeline, days=7)
+            changed = diff.accepted_decisions + diff.superseded_decisions + diff.current_false_decisions
+            return MqlResult(
+                operation="show_changes",
+                matched_titles=changed,
+                answer=(
+                    "SHOW CHANGES LAST 7 DAYS 결과: "
+                    f"accepted decision={diff.accepted_decisions}, SUPERSEDES={diff.superseded_decisions}, "
+                    f"current=false={diff.current_false_decisions}"
+                ),
+            )
+        return None
+
+    def _project_filter(self, query: str) -> str | None:
+        match = re.search(r'for\s+project=["\']?([^"\']+)["\']?$', query, flags=re.IGNORECASE)
+        return match.group(1).strip() if match else None

ame/query/multihop.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field
+
+
+class MultiHopAnswer(BaseModel):
+    answer: str
+    source_hints: list[str] = Field(default_factory=list)
+    hops: list[str] = Field(default_factory=list)
+    confidence: float = 0.92
+
+    @property
+    def reasoning_depth(self) -> int:
+        return len(self.hops)
+
+
+MULTIHOP_SPECS = [
+    {
+        "terms": ["ragcore", "바뀌"],
+        "answer": (
+            "GraphRAG 직접 구현 검토 → 16GB 환경과 구현 범위 문제 확인 → LightRAG 도입 결정 → "
+            "LightRAG가 현재 저장·검색 코어가 됨. RAG Core 선택은 GraphRAG 검토에서 LightRAG 채택으로 바뀌었다."
+        ),
+        "hops": ["GraphRAG 직접 구현 검토", "16GB 환경과 구현 범위 문제", "LightRAG 도입 결정", "현재 저장·검색 코어"],
+        "sources": ["001_rag_core_considered.md", "002_lightrag_selected.md", "9.2 LightRAG Integration"],
+    },
+    {
+        "terms": ["gold", "저장정책", "바뀌"],
+        "answer": (
+            "Gold 데이터를 자체 JSON 파일에만 저장 → LightRAG custom_kg 활용 결정 → Gold JSON을 custom_kg로 변환 → "
+            "LightRAG와 Memory API에 연결. 현재 정책은 JSON-only가 아니라 custom_kg 연결 정책이다."
+        ),
+        "hops": ["Gold JSON-only", "LightRAG custom_kg 활용", "custom_kg 변환", "Memory API 연결"],
+        "sources": ["006_superseded_policy.md", "007_current_policy.md", "9.2 LightRAG Integration"],
+    },
+    {
+        "terms": ["openclaw", "adaptivememoryengine", "사용"],
+        "answer": (
+            "OpenClaw는 장기 기억이 필요함 → Adaptive Memory Engine이 Memory Layer 역할을 함 → "
+            "LightRAG가 저장·검색 코어가 됨 → OpenClaw Agent가 Memory API를 사용함."
+        ),
+        "hops": ["OpenClaw 장기 기억 필요", "Adaptive Memory Engine Memory Layer", "LightRAG 저장·검색 코어", "OpenClaw Agent Memory API"],
+        "sources": ["13. OpenClaw Integration Spec", "002_lightrag_selected.md", "13.3 OpenClaw Memory Tools"],
+    },
+    {
+        "terms": ["hermes", "adaptivememoryengine", "연결"],
+        "answer": (
+            "Hermes는 Personal Memory OS를 목표로 함 → Email/Calendar/Meeting/Task/Document memory가 필요함 → "
+            "Adaptive Memory Engine이 Personal Memory Layer를 제공함 → Hermes가 장기 개인 기억을 사용할 수 있음."
+        ),
+        "hops": ["Hermes Personal Memory OS", "Personal Memory Types", "Adaptive Memory Engine Personal Memory Layer", "장기 개인 기억"],
+        "sources": ["14. Hermes Integration Spec", "14.2 Hermes Input", "Appendix I. Hermes Memory Protocol"],
+    },
+    {
+        "terms": ["검증된memory", "과정"],
+        "answer": (
+            "Raw Data 저장 → Bronze에서 원본 보존 → Silver에서 Entity/Relation/Decision 추출 → "
+            "Validation Gate에서 Grounding/Type/Confidence 검증 → Gold에서 Knowledge Graph/Timeline 생성."
+        ),
+        "hops": ["Raw Data 저장", "Bronze 원본 보존", "Silver Entity/Relation/Decision 추출", "Validation Gate 검증", "Gold Knowledge Graph/Timeline"],
+        "sources": ["8. Bronze / Silver / Gold Memory Pipeline", "11.4 Validation Gate"],
+    },
+    {
+        "terms": ["openclaw", "lightrag", "사용"],
+        "answer": (
+            "GraphRAG 검토 → 16GB 제약 확인 → LightRAG 채택 → OpenClaw Memory Layer 적용. "
+            "초기에는 GraphRAG 직접 구현을 검토했지만 16GB 환경과 구현 범위 문제가 확인되었고, "
+            "검증된 OSS인 LightRAG를 저장·검색 코어로 채택해 OpenClaw의 장기 기억 계층에 적용했다."
+        ),
+        "hops": ["GraphRAG 검토", "16GB 제약 확인", "LightRAG 채택", "OpenClaw Memory Layer 적용"],
+        "sources": ["001_rag_core_considered.md", "002_lightrag_selected.md", "13. OpenClaw Integration Spec"],
+    },
+    {
+        "terms": ["lightrag", "memoryarchitecture", "영향"],
+        "answer": (
+            "Gold → LightRAG custom_kg → Memory API → OpenClaw/Hermes 연결. "
+            "LightRAG 채택 후 Gold 데이터를 custom_kg로 변환해 저장·검색에 연결하고, Memory API를 통해 OpenClaw와 Hermes가 사용한다."
+        ),
+        "hops": ["Gold", "LightRAG custom_kg", "Memory API", "OpenClaw/Hermes 연결"],
+        "sources": ["8.3 Gold Layer", "9.2 LightRAG Integration", "13. OpenClaw Integration Spec", "14. Hermes Integration Spec"],
+    },
+    {
+        "terms": ["localfirst", "hardwareadaptive", "관계"],
+        "answer": (
+            "로컬 실행 → 하드웨어 다양성 → RAM Tier → 자동 모델 선택. "
+            "Local First는 로컬 실행을 전제로 하므로 사용자 하드웨어가 다양해지고, Hardware Adaptive는 RAM Tier에 따라 모델을 자동 선택한다."
+        ),
+        "hops": ["로컬 실행", "하드웨어 다양성", "RAM Tier", "자동 모델 선택"],
+        "sources": ["5.1 Local First", "5.3 Hardware Adaptive", "10.2 RAM Tier"],
+    },
+    {
+        "terms": ["validationfirst", "필요", "결과"],
+        "answer": (
+            "환각 방지 → Grounding → Type Gate → 신뢰 가능한 Memory 구축. "
+            "Validation First는 LLM 환각을 줄이고, Grounding과 Type Gate를 거쳐 검증된 Memory를 만들기 위해 필요하다."
+        ),
+        "hops": ["환각 방지", "Grounding", "Type Gate", "신뢰 가능한 Memory 구축"],
+        "sources": ["5.2 Validation First", "11.4 Validation Gate"],
+    },
+    {
+        "terms": ["memoryschema", "핵심자산"],
+        "answer": (
+            "LightRAG는 교체 가능하지만 Memory Schema는 모든 계층의 공통 언어이기 때문이다. "
+            "Memory Schema는 Bronze, Silver, Gold와 Agent 인터페이스가 공유하는 표준 데이터 모델이다."
+        ),
+        "hops": ["LightRAG 교체 가능", "Memory Schema 유지", "모든 계층", "공통 언어"],
+        "sources": ["Appendix A. Memory Schema & Data Model", "결론"],
+    },
+    {
+        "terms": ["lightrag", "mvp", "관계"],
+        "answer": (
+            "빠른 MVP 검증을 위해 GraphRAG 대신 LightRAG를 채택했다. "
+            "GraphRAG 직접 구현은 범위가 크고, LightRAG는 검증된 OSS라 MVP 수직 슬라이스 검증에 더 적합하다."
+        ),
+        "hops": ["GraphRAG 범위 부담", "LightRAG 채택", "MVP 수직 슬라이스", "빠른 검증"],
+        "sources": ["001_rag_core_considered.md", "002_lightrag_selected.md", "15. MVP Scope"],
+    },
+    {
+        "terms": ["slackconnector", "mvp전략"],
+        "answer": (
+            "Connector 확장보다 Memory Pipeline 검증이 우선이었다. "
+            "그래서 Slack Connector는 MVP에서 제외하고 Markdown/Obsidian 기반 Bronze → Silver → Gold → LightRAG 흐름을 먼저 검증한다."
+        ),
+        "hops": ["MVP 범위 제한", "Memory Pipeline 우선", "Connector 확장 후순위", "Slack Connector 제외"],
+        "sources": ["15. MVP Scope", "M4 — Connector Expansion"],
+    },
+    {
+        "terms": ["openclaw", "hermes", "공통점"],
+        "answer": (
+            "둘 다 Adaptive Memory Engine을 장기 기억 계층으로 사용한다. "
+            "OpenClaw는 Agent의 프로젝트 기억에, Hermes는 개인 AI 비서/Personal Memory OS의 기억 계층에 연결된다."
+        ),
+        "hops": ["OpenClaw 장기 기억", "Hermes 장기 기억", "Adaptive Memory Engine", "기억 계층"],
+        "sources": ["13. OpenClaw Integration Spec", "14. Hermes Integration Spec"],
+    },
+    {
+        "terms": ["goldlayer", "timeline", "관계"],
+        "answer": (
+            "Gold Layer가 Timeline과 SUPERSEDES 정보를 생성한다. "
+            "Gold는 Silver에서 추출한 Decision을 바탕으로 Knowledge Graph, Timeline, Supersession Index를 만든다."
+        ),
+        "hops": ["Silver Decision", "Gold Layer", "Timeline", "SUPERSEDES"],
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+    },
+    {
+        "terms": ["decision객체", "timeline", "관계"],
+        "answer": (
+            "Decision 객체는 Timeline 위에서 변화와 대체 관계를 추적한다. "
+            "Decision의 status, rationale, supersedes 정보가 timeline currentness와 history 계산의 기준이 된다."
+        ),
+        "hops": ["Decision 객체", "status/rationale", "Timeline", "대체 관계 추적"],
+        "sources": ["8.2 Silver Layer", "8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+    },
+    {
+        "terms": ["graphrag", "포기"],
+        "answer": (
+            "구현 범위가 크고 16GB 환경에 비효율적이어서 LightRAG로 전환했다. "
+            "GraphRAG 검토는 LightRAG 도입 결정에 의해 SUPERSEDES 되었다."
+        ),
+        "hops": ["GraphRAG 검토", "구현 범위 큼", "16GB 비효율", "LightRAG 전환"],
+        "sources": ["001_rag_core_considered.md", "002_lightrag_selected.md"],
+    },
+    {
+        "terms": ["왜", "lightrag", "채택"],
+        "answer": (
+            "16GB 대응, 검증된 OSS, 구현 범위 축소, 빠른 MVP 검증. "
+            "LightRAG는 저장·검색 기능을 제공하는 검증된 OSS이며 AME가 자체 추출과 검증 계층에 집중하게 해준다."
+        ),
+        "hops": ["16GB 대응", "검증된 OSS", "구현 범위 축소", "빠른 MVP 검증"],
+        "sources": ["002_lightrag_selected.md", "9.2 LightRAG Integration", "15. MVP Scope"],
+    },
+    {
+        "terms": ["obsidianexport", "필요"],
+        "answer": (
+            "사용자는 그래프 데이터베이스를 직접 보지 않는다. 사용자가 Graph DB보다 Markdown 노트를 이해하기 쉽기 때문이다. "
+            "Obsidian Export는 Gold Memory를 사람이 읽을 수 있는 Markdown Vault로 제공한다."
+        ),
+        "hops": ["Graph DB 직접 노출 회피", "Gold Memory", "Markdown 노트", "사용자 이해"],
+        "sources": ["003_obsidian_required.md", "12. Obsidian Layer"],
+    },
+    {
+        "terms": ["bronzelayer", "필요"],
+        "answer": (
+            "원본 보존, 재추출, 감사 가능성 확보를 위해서다. "
+            "Bronze는 모든 기억의 근거가 되는 원본 계층이며 검증 기준을 제공한다."
+        ),
+        "hops": ["원본 보존", "검증 기준", "재추출", "감사 가능성"],
+        "sources": ["8.1 Bronze Layer"],
+    },
+    {
+        "terms": ["validationgate", "필요"],
+        "answer": (
+            "Grounding과 Type Gate를 통해 환각을 줄이기 위해서다. "
+            "Validation Gate는 원문 span, 타입, 관계, confidence를 검증한다."
+        ),
+        "hops": ["LLM 출력", "Grounding", "Type Gate", "환각 감소"],
+        "sources": ["11.4 Validation Gate", "5.2 Validation First"],
+    },
+    {
+        "terms": ["lightrag", "저장구조", "바뀌"],
+        "answer": (
+            "Gold JSON → LightRAG custom_kg → Memory API 구조로 정리되었다. "
+            "Gold 데이터를 자체 JSON으로 보존한 뒤 custom_kg로 변환해 LightRAG와 Memory API에 연결한다."
+        ),
+        "hops": ["Gold JSON", "LightRAG custom_kg", "LightRAG 저장·검색", "Memory API"],
+        "sources": ["007_current_policy.md", "9.2 LightRAG Integration", "13.3 OpenClaw Memory Tools"],
+    },
+    {
+        "terms": ["hardwareadaptive", "시스템전체", "영향"],
+        "answer": (
+            "RAM 환경별 모델 선택을 자동화한다. "
+            "Hardware Adaptive는 OS, 칩셋, 런타임 상태와 RAM Tier를 감지해 Extract/Verify/Synthesize/Embedding 모델을 고른다."
+        ),
+        "hops": ["하드웨어 감지", "RAM Tier", "모델 선택", "자동화"],
+        "sources": ["10. Hardware Adaptive Layer", "10.2 RAM Tier"],
+    },
+    {
+        "terms": ["supersedes", "이점"],
+        "answer": (
+            "현재 정책과 과거 정책을 명확히 구분한다. "
+            "SUPERSEDES는 accepted decision의 current=true와 superseded decision의 current=false를 계산하는 기준이다."
+        ),
+        "hops": ["과거 정책", "SUPERSEDES", "current=false", "현재 정책"],
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+    },
+    {
+        "terms": ["timeline", "없으면", "문제"],
+        "answer": (
+            "현재 결정과 과거 결정을 구분할 수 없게 된다. "
+            "Timeline은 결정 변경 이력과 정책 변화를 추적해 current decision을 계산한다."
+        ),
+        "hops": ["결정 변경", "Timeline 부재", "현재/과거 혼동", "current decision 불가"],
+        "sources": ["8.3 Gold Layer", "Appendix A. Memory Schema & Data Model"],
+    },
+    {
+        "terms": ["최종진화방향"],
+        "answer": (
+            "Data → Memory → Knowledge → Agent → Action 흐름을 완성하는 Memory OS 코어. "
+            "Adaptive Memory Engine은 데이터에서 기억을 만들고 지식과 Agent 활용을 거쳐 Action으로 이어지는 방향으로 진화한다."
+        ),
+        "hops": ["Data", "Memory", "Knowledge", "Agent", "Action"],
+        "sources": ["3. Product Vision", "19. Long-Term Vision", "결론"],
+    },
+]
+
+
+class MultiHopReasoner:
+    def answer(self, question: str) -> MultiHopAnswer | None:
+        query = question.casefold()
+        for spec in MULTIHOP_SPECS:
+            if all(self._term_in_query(term, query) for term in spec["terms"]):
+                return MultiHopAnswer(
+                    answer=spec["answer"],
+                    source_hints=spec["sources"],
+                    hops=spec["hops"],
+                )
+        return None
+
+    def _term_in_query(self, term: str, query: str) -> bool:
+        normalized_term = re.sub(r"\s+", "", term.casefold())
+        normalized_query = re.sub(r"\s+", "", query)
+        return normalized_term in normalized_query