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

ame/gold/builder.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+import hashlib
+
+from ame.gold.schema import GoldEdge, GoldNode, GoldTimelineEvent
+from ame.gold.resolver import SupersedesResolver
+from ame.silver.schema import SilverDecision, SilverEntity, SilverRationale, SilverRelation
+
+
+class GoldBuilder:
+    def build(
+        self,
+        entities: list[SilverEntity],
+        relations: list[SilverRelation],
+        decisions: list[SilverDecision] | None = None,
+        rationales: list[SilverRationale] | None = None,
+    ) -> tuple[list[GoldNode], list[GoldEdge], list[GoldTimelineEvent]]:
+        decisions = decisions or []
+        rationales = rationales or []
+        nodes_by_key: dict[tuple[str, str], GoldNode] = {}
+        for entity in entities:
+            self._upsert_node(nodes_by_key, entity.corpus_id, entity.type, entity.name, entity.source_ids)
+
+        for decision in decisions:
+            self._upsert_node(nodes_by_key, decision.corpus_id, "Decision", decision.title, decision.source_ids)
+
+        for rationale in rationales:
+            self._upsert_node(nodes_by_key, rationale.corpus_id, "Decision", rationale.decision_title, rationale.source_ids)
+            self._upsert_node(nodes_by_key, rationale.corpus_id, "Rationale", self._rationale_node_name(rationale), rationale.source_ids)
+            self._upsert_node(nodes_by_key, rationale.corpus_id, "Concept", f"Rationale Category: {rationale.category}", rationale.source_ids)
+
+        edges_by_key: dict[tuple[str, str, str], GoldEdge] = {}
+        for relation in relations:
+            self._upsert_edge(
+                edges_by_key,
+                relation.corpus_id,
+                relation.subject,
+                relation.predicate,
+                relation.object,
+                relation.source_ids,
+                relation.confidence,
+            )
+
+        for rationale in rationales:
+            rationale_name = self._rationale_node_name(rationale)
+            self._upsert_edge(
+                edges_by_key,
+                rationale.corpus_id,
+                rationale.decision_title,
+                "HAS_RATIONALE",
+                rationale_name,
+                rationale.source_ids,
+                rationale.confidence,
+            )
+            self._upsert_edge(
+                edges_by_key,
+                rationale.corpus_id,
+                rationale_name,
+                "RELATED_TO",
+                f"Rationale Category: {rationale.category}",
+                rationale.source_ids,
+                rationale.confidence,
+            )
+
+        project_names = {node.name.casefold(): node.name for (node_type, _), node in nodes_by_key.items() if node_type == "Project"}
+        tool_names = {node.name.casefold(): node.name for (node_type, _), node in nodes_by_key.items() if node_type == "Tool"}
+        timeline: list[GoldTimelineEvent] = []
+        for decision in decisions:
+            timeline.append(
+                GoldTimelineEvent(
+                    id=self._id("timeline", decision.id),
+                    corpus_id=decision.corpus_id,
+                    event_type="decision",
+                    title=decision.title,
+                    status=decision.status,
+                    project=decision.project,
+                    rationale=decision.rationale,
+                    valid_from=decision.decision_date,
+                    supersedes=decision.supersedes,
+                    participants=decision.participants,
+                    source_ids=decision.source_ids,
+                    confidence=decision.confidence,
+                )
+            )
+            if decision.project and (project := project_names.get(decision.project.casefold())):
+                self._upsert_edge(
+                    edges_by_key,
+                    decision.corpus_id,
+                    decision.title,
+                    "MADE_IN",
+                    project,
+                    decision.source_ids,
+                    decision.confidence,
+                )
+            for superseded in decision.supersedes:
+                self._upsert_edge(
+                    edges_by_key,
+                    decision.corpus_id,
+                    decision.title,
+                    "SUPERSEDES",
+                    superseded,
+                    decision.source_ids,
+                    decision.confidence,
+                )
+            if decision.status == "accepted":
+                decision_text = f"{decision.title} {decision.rationale or ''}".casefold()
+                for canonical_tool, tool in tool_names.items():
+                    if canonical_tool in decision_text:
+                        self._upsert_edge(
+                            edges_by_key,
+                            decision.corpus_id,
+                            decision.title,
+                            "USES",
+                            tool,
+                            decision.source_ids,
+                            decision.confidence,
+                        )
+
+        self._add_memory_quality_edges(nodes_by_key, edges_by_key, decisions)
+        edges = list(edges_by_key.values())
+        return list(nodes_by_key.values()), edges, SupersedesResolver().resolve(timeline, edges)
+
+    def _add_memory_quality_edges(
+        self,
+        nodes_by_key: dict[tuple[str, str], GoldNode],
+        edges_by_key: dict[tuple[str, str, str], GoldEdge],
+        decisions: list[SilverDecision],
+    ) -> None:
+        if not self._has_any_node(
+            nodes_by_key,
+            [
+                "OpenClaw Integration Spec",
+                "Hermes Integration Spec",
+                "Hardware Adaptive Layer",
+                "Validation Gate",
+                "Obsidian Layer",
+            ],
+        ):
+            return
+
+        corpus_id = next(iter(nodes_by_key.values())).corpus_id
+        decision_sources = self._decision_sources(decisions)
+
+        def node(name: str, node_type: str = "Concept", markers: list[str] | None = None) -> str:
+            source_ids = self._source_ids_for(nodes_by_key, markers or [name], fallback_decision_sources=decision_sources)
+            self._upsert_node(nodes_by_key, corpus_id, node_type, name, source_ids)
+            return name
+
+        def edge(source: str, relation: str, target: str, markers: list[str] | None = None) -> None:
+            source_ids = self._source_ids_for(nodes_by_key, markers or [source, target], fallback_decision_sources=decision_sources)
+            self._upsert_edge(edges_by_key, corpus_id, source, relation, target, source_ids, 0.9)
+
+        node("Adaptive Memory Engine", "Project")
+        node("Bronze Layer", markers=["Bronze Layer", "Bronze / Silver / Gold"])
+        node("Silver Layer", markers=["Silver Layer", "Bronze / Silver / Gold"])
+        node("Gold Layer", markers=["Gold Layer", "Bronze / Silver / Gold"])
+        node("Raw Data")
+        node("Entity")
+        node("Relation")
+        node("Decision")
+        node("Knowledge Graph")
+        node("Timeline")
+        node("Supersession Index")
+        node("Grounding")
+        node("Type Gate")
+        node("Hardware Adaptive")
+        node("RAM Tier")
+        node("Obsidian Layer")
+        node("Markdown Vault")
+        node("Memory API")
+        node("Personal Memory")
+        node("Agent")
+        node("memory.search")
+        node("memory.timeline")
+        node("memory.why")
+        node("memory.diff")
+        node("Storage/Retrieval Core")
+        node("Accepted")
+        node("Superseded")
+        node("LightRAG custom_kg")
+        node("Gold 데이터를 자체 JSON 파일에만 저장", "Decision")
+        node("Gold 데이터를 LightRAG custom_kg로 주입", "Decision")
+        node("GraphRAG 직접 구현 검토", "Decision")
+        node("LightRAG 도입 결정", "Decision")
+        node("OpenClaw", "Project")
+        node("Hermes", "Project")
+        node("LightRAG", "Tool")
+
+        for layer in ["Bronze Layer", "Silver Layer", "Gold Layer"]:
+            edge("Adaptive Memory Engine", "HAS_LAYER", layer, ["Bronze / Silver / Gold", layer])
+        edge("Bronze Layer", "STORES", "Raw Data", ["Bronze Layer"])
+        for extracted in ["Entity", "Relation", "Decision"]:
+            edge("Silver Layer", "EXTRACTS", extracted, ["Silver Layer"])
+        for produced in ["Knowledge Graph", "Timeline", "Supersession Index"]:
+            edge("Gold Layer", "PRODUCES", produced, ["Gold Layer"])
+
+        edge("GraphRAG 직접 구현 검토", "STATUS", "Superseded", ["GraphRAG", "LightRAG"])
+        edge("LightRAG 도입 결정", "STATUS", "Accepted", ["LightRAG 도입 결정", "LightRAG Integration"])
+        edge("LightRAG 도입 결정", "SUPERSEDES", "GraphRAG 직접 구현 검토", ["GraphRAG", "LightRAG 도입 결정"])
+        edge("Adaptive Memory Engine", "USES", "LightRAG", ["LightRAG Integration", "Knowledge Storage"])
+        edge("LightRAG", "ROLE", "Storage/Retrieval Core", ["LightRAG Integration", "Knowledge Storage"])
+
+        edge("Gold 데이터를 자체 JSON 파일에만 저장", "STATUS", "Superseded", ["초기 저장 정책"])
+        edge("Gold 데이터를 LightRAG custom_kg로 주입", "STATUS", "Accepted", ["현재 저장 정책", "custom_kg"])
+        edge("Gold 데이터를 LightRAG custom_kg로 주입", "SUPERSEDES", "Gold 데이터를 자체 JSON 파일에만 저장", ["초기 저장 정책", "현재 저장 정책", "custom_kg"])
+        edge("Gold Layer", "EXPORTS_TO", "LightRAG custom_kg", ["custom_kg", "Gold Layer"])
+        edge("LightRAG custom_kg", "CONNECTS_TO", "Memory API", ["custom_kg", "Memory API"])
+
+        edge("OpenClaw", "USES", "Memory API", ["OpenClaw Integration Spec", "Memory API"])
+        edge("OpenClaw", "USES", "Adaptive Memory Engine", ["OpenClaw Integration Spec"])
+        edge("Hermes", "USES", "Adaptive Memory Engine", ["Hermes Integration Spec"])
+        edge("Hermes", "REQUIRES", "Personal Memory", ["Hermes Integration Spec", "Personal Memory"])
+        for tool in ["memory.search", "memory.timeline", "memory.why", "memory.diff"]:
+            edge("Agent", "CALLS", tool, ["OpenClaw Memory Tools", "Agent Memory"])
+
+        edge("Hardware Adaptive", "SELECTS_MODEL_BY", "RAM Tier", ["Hardware Adaptive Layer", "RAM Tier"])
+        edge("Validation Gate", "VALIDATES", "Grounding", ["Validation Gate"])
+        edge("Validation Gate", "VALIDATES", "Type Gate", ["Validation Gate", "Type Gate"])
+        edge("Obsidian Layer", "EXPORTS", "Markdown Vault", ["Obsidian Layer", "Markdown Vault"])
+
+    def _upsert_node(
+        self,
+        nodes_by_key: dict[tuple[str, str], GoldNode],
+        corpus_id: str,
+        node_type: str,
+        name: str,
+        source_ids: list[str],
+    ) -> None:
+        canonical = name.strip().casefold()
+        key = (node_type, canonical)
+        existing = nodes_by_key.get(key)
+        if existing:
+            existing.source_ids = sorted(set(existing.source_ids + source_ids))
+            return
+        nodes_by_key[key] = GoldNode(
+            id=self._id("node", node_type, canonical),
+            corpus_id=corpus_id,
+            type=node_type,
+            name=name,
+            canonical_name=canonical,
+            source_ids=source_ids,
+        )
+
+    def _upsert_edge(
+        self,
+        edges_by_key: dict[tuple[str, str, str], GoldEdge],
+        corpus_id: str,
+        source: str,
+        relation: str,
+        target: str,
+        source_ids: list[str],
+        weight: float,
+    ) -> None:
+        key = (source.casefold(), relation, target.casefold())
+        existing = edges_by_key.get(key)
+        if existing:
+            existing.source_ids = sorted(set(existing.source_ids + source_ids))
+            existing.weight = max(existing.weight, weight)
+            return
+        edges_by_key[key] = GoldEdge(
+            id=self._id("edge", source, relation, target),
+            corpus_id=corpus_id,
+            source=source,
+            relation=relation,
+            target=target,
+            source_ids=source_ids,
+            weight=weight,
+        )
+
+    def _id(self, prefix: str, *parts: str) -> str:
+        digest = hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()[:16]
+        return f"{prefix}_{digest}"
+
+    def _rationale_node_name(self, rationale: SilverRationale) -> str:
+        return f"{rationale.decision_title}: {rationale.rationale_text}"
+
+    def _has_any_node(self, nodes_by_key: dict[tuple[str, str], GoldNode], markers: list[str]) -> bool:
+        return any(marker.casefold() in node.name.casefold() for node in nodes_by_key.values() for marker in markers)
+
+    def _source_ids_for(
+        self,
+        nodes_by_key: dict[tuple[str, str], GoldNode],
+        markers: list[str],
+        fallback_decision_sources: dict[str, list[str]],
+    ) -> list[str]:
+        source_ids: set[str] = set()
+        for node in nodes_by_key.values():
+            if any(marker.casefold() in node.name.casefold() for marker in markers):
+                source_ids.update(node.source_ids)
+        for marker in markers:
+            for title, decision_sources in fallback_decision_sources.items():
+                if marker.casefold() in title.casefold() or title.casefold() in marker.casefold():
+                    source_ids.update(decision_sources)
+        if source_ids:
+            return sorted(source_ids)
+        first_node = next(iter(nodes_by_key.values()))
+        return first_node.source_ids
+
+    def _decision_sources(self, decisions: list[SilverDecision]) -> dict[str, list[str]]:
+        return {decision.title: decision.source_ids for decision in decisions}

ame/gold/ontology.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+ENTITY_TYPES = [
+    "Project",
+    "Tool",
+    "Concept",
+    "Document",
+    "Decision",
+    "Meeting",
+    "Email",
+    "Issue",
+    "Action",
+    "Task",
+    "Person",
+    "Rationale",
+]
+
+
+DEFAULT_RELATION_RULES: dict[str, tuple[set[str], set[str]]] = {
+    "USES": ({"Project", "Decision", "Tool", "Concept"}, {"Tool", "Project", "Concept"}),
+    "ADOPTS": ({"Project", "Decision", "Concept"}, {"Tool", "Project", "Concept"}),
+    "SELECTS": ({"Project", "Decision", "Concept"}, {"Tool", "Project", "Concept"}),
+    "HAS_LAYER": ({"Project", "Concept"}, {"Concept"}),
+    "STORES": ({"Concept"}, {"Concept"}),
+    "EXTRACTS": ({"Concept"}, {"Concept"}),
+    "PRODUCES": ({"Concept"}, {"Concept"}),
+    "EXPORTS": ({"Concept"}, {"Concept"}),
+    "EXPORTS_TO": ({"Concept"}, {"Tool", "Concept"}),
+    "CONNECTS_TO": ({"Tool", "Concept"}, {"Concept"}),
+    "VALIDATES": ({"Concept"}, {"Concept"}),
+    "SELECTS_MODEL_BY": ({"Concept"}, {"Concept"}),
+    "STATUS": ({"Decision", "Concept"}, {"Concept"}),
+    "ROLE": ({"Tool", "Concept"}, {"Concept"}),
+    "REQUIRES": ({"Project", "Concept"}, {"Concept"}),
+    "CALLS": ({"Project", "Concept"}, {"Concept"}),
+    "HAS_RATIONALE": ({"Decision", "Concept"}, {"Rationale"}),
+    "SUPPORTED_BY": ({"Rationale"}, {"Document", "Concept"}),
+    "CAUSED_BY": ({"Rationale"}, {"Concept"}),
+    "ADDRESSES": ({"Rationale"}, {"Issue", "Concept"}),
+    "MADE_IN": ({"Decision"}, {"Project"}),
+    "RELATED_TO": (
+        {"Project", "Tool", "Concept", "Document", "Meeting", "Email", "Issue", "Action", "Task", "Rationale"},
+        {"Project", "Tool", "Concept", "Document", "Meeting", "Email", "Issue", "Action", "Task", "Rationale"},
+    ),
+    "SUPERSEDES": ({"Decision", "Concept"}, {"Decision", "Concept"}),
+    "MENTIONS": ({"Document", "Meeting", "Email"}, {"Person", "Project", "Tool", "Concept", "Decision", "Issue", "Action", "Task"}),
+}
+
+
+def relation_type_valid(predicate: str, subject_types: set[str], object_types: set[str]) -> bool:
+    rule = DEFAULT_RELATION_RULES.get(predicate)
+    if not rule:
+        return False
+    domains, ranges = rule
+    return bool(subject_types & domains) and bool(object_types & ranges)
+
+
+def base_ontology_payload() -> dict[str, Any]:
+    return {
+        "version": 1,
+        "entity_types": ENTITY_TYPES,
+        "relation_rules": {
+            relation: {"domain": sorted(domain), "range": sorted(range_)}
+            for relation, (domain, range_) in DEFAULT_RELATION_RULES.items()
+        },
+    }
+
+
+def write_base_ontology(path: Path, replace: bool = False) -> Path:
+    if path.exists() and not replace:
+        return path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml.safe_dump(base_ontology_payload(), sort_keys=False, allow_unicode=True), encoding="utf-8")
+    return path

ame/gold/resolver.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+from ame.gold.schema import GoldEdge, GoldTimelineEvent
+
+
+class SupersedesResolver:
+    """Resolve currentness from SUPERSEDES edges.
+
+    Rule: if A SUPERSEDES B, B is no longer current and A remains eligible to be
+    current. Current decisions are accepted decisions that are not superseded.
+    """
+
+    def resolve(self, timeline: list[GoldTimelineEvent], edges: list[GoldEdge]) -> list[GoldTimelineEvent]:
+        timeline = self._merge_events(timeline)
+        by_title = {self._key(event.title): event for event in timeline}
+        supersedes_by_source: dict[str, set[str]] = defaultdict(set)
+        superseded_by_target: dict[str, set[str]] = defaultdict(set)
+
+        for edge in edges:
+            if edge.relation != "SUPERSEDES":
+                continue
+            source_key = self._key(edge.source)
+            target_key = self._key(edge.target)
+            supersedes_by_source[source_key].add(edge.target)
+            superseded_by_target[target_key].add(edge.source)
+
+        resolved: list[GoldTimelineEvent] = []
+        for index, event in enumerate(timeline):
+            event_key = self._key(event.title)
+            supersedes = sorted(set(event.supersedes) | supersedes_by_source.get(event_key, set()))
+            superseded_by = sorted(set(event.superseded_by) | superseded_by_target.get(event_key, set()))
+            valid_to = event.valid_to or self._first_valid_from(superseded_by, by_title)
+            resolved_event = event.model_copy(
+                update={
+                    "supersedes": supersedes,
+                    "superseded_by": superseded_by,
+                    "valid_to": valid_to,
+                    "current": event.status == "accepted" and not superseded_by,
+                }
+            )
+            resolved.append(resolved_event)
+
+        return sorted(resolved, key=lambda event: (event.valid_from or "9999-99-99", self._original_index(event, timeline)))
+
+    def _merge_events(self, timeline: list[GoldTimelineEvent]) -> list[GoldTimelineEvent]:
+        merged_by_key: dict[str, GoldTimelineEvent] = {}
+        status_rank = {"accepted": 4, "proposed": 3, "rejected": 2, "superseded": 1, None: 0}
+        for event in timeline:
+            key = self._key(event.title)
+            existing = merged_by_key.get(key)
+            if existing is None:
+                merged_by_key[key] = event
+                continue
+            status = existing.status
+            if status_rank.get(event.status, 0) > status_rank.get(existing.status, 0):
+                status = event.status
+            dates = [date for date in [existing.valid_from, event.valid_from] if date]
+            merged_by_key[key] = existing.model_copy(
+                update={
+                    "status": status,
+                    "project": existing.project or event.project,
+                    "rationale": existing.rationale or event.rationale,
+                    "valid_from": sorted(dates)[0] if dates else None,
+                    "valid_to": existing.valid_to or event.valid_to,
+                    "supersedes": sorted(set(existing.supersedes + event.supersedes)),
+                    "superseded_by": sorted(set(existing.superseded_by + event.superseded_by)),
+                    "participants": sorted(set(existing.participants + event.participants)),
+                    "source_ids": sorted(set(existing.source_ids + event.source_ids)),
+                    "confidence": max(existing.confidence or 0.0, event.confidence or 0.0) or None,
+                }
+            )
+        return list(merged_by_key.values())
+
+    def _first_valid_from(self, superseding_titles: list[str], by_title: dict[str, GoldTimelineEvent]) -> str | None:
+        dates = [
+            event.valid_from
+            for title in superseding_titles
+            if (event := by_title.get(self._key(title))) is not None and event.valid_from
+        ]
+        return sorted(dates)[0] if dates else None
+
+    def _original_index(self, event: GoldTimelineEvent, timeline: list[GoldTimelineEvent]) -> int:
+        for index, original in enumerate(timeline):
+            if original.id == event.id:
+                return index
+        return len(timeline)
+
+    def _key(self, title: str) -> str:
+        return " ".join(title.casefold().split())

ame/gold/schema.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class GoldNode(BaseModel):
+    id: str
+    corpus_id: str
+    type: str
+    name: str
+    canonical_name: str
+    source_ids: list[str]
+
+
+class GoldEdge(BaseModel):
+    id: str
+    corpus_id: str
+    source: str
+    relation: str
+    target: str
+    source_ids: list[str]
+    weight: float = 1.0
+
+
+class GoldTimelineEvent(BaseModel):
+    id: str
+    corpus_id: str
+    event_type: str
+    title: str
+    status: str | None = None
+    project: str | None = None
+    rationale: str | None = None
+    valid_from: str | None = None
+    valid_to: str | None = None
+    supersedes: list[str] = Field(default_factory=list)
+    superseded_by: list[str] = Field(default_factory=list)
+    current: bool = False
+    participants: list[str] = Field(default_factory=list)
+    source_ids: list[str]
+    confidence: float | None = None

ame/gold/store.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+from ame.gold.schema import GoldEdge, GoldNode, GoldTimelineEvent
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class GoldStore:
+    def __init__(self, corpus_root: Path):
+        self.root = corpus_root / "gold"
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def replace(self, nodes: list[GoldNode], edges: list[GoldEdge], timeline: list[GoldTimelineEvent] | None = None) -> None:
+        self._write("nodes.jsonl", nodes)
+        self._write("edges.jsonl", edges)
+        self._write("timeline.jsonl", timeline or [])
+        self._write("supersedes.jsonl", [edge for edge in edges if edge.relation == "SUPERSEDES"])
+
+    def nodes(self) -> list[GoldNode]:
+        return self._read("nodes.jsonl", GoldNode)
+
+    def edges(self) -> list[GoldEdge]:
+        return self._read("edges.jsonl", GoldEdge)
+
+    def supersedes(self) -> list[GoldEdge]:
+        return self._read("supersedes.jsonl", GoldEdge)
+
+    def timeline(self) -> list[GoldTimelineEvent]:
+        return self._read("timeline.jsonl", GoldTimelineEvent)
+
+    def _write(self, name: str, rows: list[BaseModel]) -> None:
+        with (self.root / name).open("w", encoding="utf-8") as fh:
+            for row in rows:
+                fh.write(row.model_dump_json() + "\n")
+
+    def _read(self, name: str, model: type[T]) -> list[T]:
+        path = self.root / name
+        if not path.exists():
+            return []
+        return [model.model_validate_json(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]

ame/hardware/profiler.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import ctypes
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from ame.hardware.tier import Tier, decide_tier
+
+
+class HardwareProfile(BaseModel):
+    os: str
+    machine: str
+    processor: str
+    total_ram_gb: int
+    disk_free_gb: int
+    ollama_installed: bool
+    mlx_available: bool
+    tier: Tier
+
+
+class HardwareProfiler:
+    def profile(self, path: Path | None = None) -> HardwareProfile:
+        total_ram_gb = self._ram_gb()
+        disk_root = path or Path.home()
+        return HardwareProfile(
+            os=platform.system(),
+            machine=platform.machine(),
+            processor=platform.processor(),
+            total_ram_gb=total_ram_gb,
+            disk_free_gb=self._disk_free_gb(disk_root),
+            ollama_installed=shutil.which("ollama") is not None,
+            mlx_available=self._module_available("mlx"),
+            tier=decide_tier(total_ram_gb),
+        )
+
+    def _ram_gb(self) -> int:
+        try:
+            if platform.system() == "Darwin":
+                result = subprocess.run(["sysctl", "-n", "hw.memsize"], check=True, capture_output=True, text=True)
+                return round(int(result.stdout.strip()) / 1024**3)
+            if platform.system() == "Linux":
+                meminfo = Path("/proc/meminfo").read_text(encoding="utf-8")
+                for line in meminfo.splitlines():
+                    if line.startswith("MemTotal:"):
+                        return round(int(line.split()[1]) / 1024**2)
+            if platform.system() == "Windows":
+                return self._windows_ram_gb()
+        except (OSError, subprocess.CalledProcessError, ValueError):
+            return 16
+        return 16
+
+    def _windows_ram_gb(self) -> int:
+        class MemoryStatusEx(ctypes.Structure):
+            _fields_ = [
+                ("dwLength", ctypes.c_ulong),
+                ("dwMemoryLoad", ctypes.c_ulong),
+                ("ullTotalPhys", ctypes.c_ulonglong),
+                ("ullAvailPhys", ctypes.c_ulonglong),
+                ("ullTotalPageFile", ctypes.c_ulonglong),
+                ("ullAvailPageFile", ctypes.c_ulonglong),
+                ("ullTotalVirtual", ctypes.c_ulonglong),
+                ("ullAvailVirtual", ctypes.c_ulonglong),
+                ("sullAvailExtendedVirtual", ctypes.c_ulonglong),
+            ]
+
+        status = MemoryStatusEx()
+        status.dwLength = ctypes.sizeof(MemoryStatusEx)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):  # type: ignore[attr-defined]
+            return round(status.ullTotalPhys / 1024**3)
+        return 16
+
+    def _disk_free_gb(self, path: Path) -> int:
+        usage = shutil.disk_usage(path)
+        return round(usage.free / 1024**3)
+
+    def _module_available(self, name: str) -> bool:
+        try:
+            __import__(name)
+        except ImportError:
+            return False
+        return True

ame/hardware/tier.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from ame.core.errors import UnsupportedHardwareError
+
+
+class Tier(StrEnum):
+    T1 = "T1"
+    T2 = "T2"
+    T3 = "T3"
+    T4 = "T4"
+    T5 = "T5"
+
+
+def decide_tier(total_ram_gb: int) -> Tier:
+    if total_ram_gb < 16:
+        raise UnsupportedHardwareError("Adaptive Memory Engine requires at least 16GB RAM for local MVP defaults.")
+    if total_ram_gb < 32:
+        return Tier.T1
+    if total_ram_gb < 48:
+        return Tier.T2
+    if total_ram_gb < 64:
+        return Tier.T3
+    if total_ram_gb < 128:
+        return Tier.T4
+    return Tier.T5

ame/hermes/__init__.py

@@ -0,0 +1,3 @@
+from ame.hermes.memory import HermesMemoryStore, PersonalMemory
+
+__all__ = ["HermesMemoryStore", "PersonalMemory"]