agmem 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

memvcs/commands/when.py

@@ -0,0 +1,115 @@
+"""
+agmem when - Find when a specific fact was learned.
+"""
+
+import argparse
+from pathlib import Path
+
+from ..commands.base import require_repo
+from ..core.objects import Commit, Tree, Blob
+
+
+class WhenCommand:
+    """Find when a fact was learned in memory history."""
+
+    name = "when"
+    help = "Find when a specific fact was learned"
+
+    @staticmethod
+    def add_arguments(parser: argparse.ArgumentParser):
+        parser.add_argument(
+            "fact",
+            nargs="?",
+            help="Fact or text to search for (e.g., 'user prefers dark mode')",
+        )
+        parser.add_argument(
+            "--file",
+            "-f",
+            help="Limit search to specific file (e.g., semantic/preferences.md)",
+        )
+        parser.add_argument(
+            "--limit",
+            "-n",
+            type=int,
+            default=10,
+            help="Max commits to report (default: 10)",
+        )
+
+    @staticmethod
+    def execute(args) -> int:
+        repo, code = require_repo()
+        if code != 0:
+            return code
+
+        if not args.fact:
+            print("Error: Fact to search for is required.")
+            print('Usage: agmem when "fact to find" [--file path]')
+            return 1
+
+        fact_lower = args.fact.lower()
+        file_filter = args.file.replace("current/", "").lstrip("/") if args.file else None
+
+        # Walk commit history from HEAD
+        head = repo.refs.get_head()
+        commit_hash = (
+            repo.refs.get_branch_commit(head["value"])
+            if head["type"] == "branch"
+            else head.get("value")
+        )
+
+        found = []
+        seen = set()
+        while commit_hash and len(found) < args.limit:
+            if commit_hash in seen:
+                break
+            seen.add(commit_hash)
+
+            commit = Commit.load(repo.object_store, commit_hash)
+            if not commit:
+                break
+
+            tree = repo.get_commit_tree(commit_hash)
+            if not tree:
+                commit_hash = commit.parents[0] if commit.parents else None
+                continue
+
+            # Check each file in tree
+            for entry in tree.entries:
+                path = entry.path + "/" + entry.name if entry.path else entry.name
+                if file_filter and path != file_filter:
+                    continue
+                if entry.obj_type != "blob":
+                    continue
+                blob = Blob.load(repo.object_store, entry.hash)
+                if not blob:
+                    continue
+                try:
+                    content = blob.content.decode("utf-8", errors="replace")
+                except Exception:
+                    continue
+                if fact_lower in content.lower():
+                    found.append(
+                        {
+                            "commit": commit_hash,
+                            "path": path,
+                            "timestamp": commit.timestamp,
+                            "author": commit.author,
+                            "message": commit.message,
+                        }
+                    )
+                    break  # One match per commit
+
+            commit_hash = commit.parents[0] if commit.parents else None
+
+        if not found:
+            scope = f" in {file_filter}" if file_filter else ""
+            print(f'No commits found containing "{args.fact}"{scope}')
+            return 0
+
+        print(f'Fact "{args.fact}" found in {len(found)} commit(s):')
+        print()
+        for i, m in enumerate(found, 1):
+            print(f"[{i}] {m['commit'][:8]} {m['timestamp']} - {m['path']}")
+            print(f"    {m['message'][:60]}")
+            print()
+        return 0

memvcs/core/access_index.py

@@ -0,0 +1,167 @@
+"""
+Access index for agmem - tracks recall access patterns for importance weighting and decay.
+
+Stores access log and recall cache in .mem/index.json.
+"""
+
+import json
+import hashlib
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+# Maximum entries in access log before compaction
+ACCESS_LOG_MAX = 10_000
+
+
+class AccessIndex:
+    """Tracks access patterns for recall, importance, and decay."""
+
+    def __init__(self, mem_dir: Path):
+        self.mem_dir = Path(mem_dir)
+        self.index_path = self.mem_dir / "index.json"
+        self._data: Optional[Dict[str, Any]] = None
+
+    def _load(self) -> Dict[str, Any]:
+        """Load index from disk."""
+        if self._data is not None:
+            return self._data
+        if self.index_path.exists():
+            try:
+                self._data = json.loads(self.index_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                self._data = self._default_structure()
+        else:
+            self._data = self._default_structure()
+        return self._data
+
+    def _default_structure(self) -> Dict[str, Any]:
+        """Return default index structure."""
+        return {
+            "version": 1,
+            "access_log": [],
+            "recall_cache": {},
+        }
+
+    def _save(self, data: Optional[Dict[str, Any]] = None) -> None:
+        """Save index to disk."""
+        data = data or self._data
+        if data is None:
+            return
+        self.mem_dir.mkdir(parents=True, exist_ok=True)
+        self.index_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        self._data = data
+
+    def record_access(self, path: str, commit: str, timestamp: Optional[str] = None) -> None:
+        """
+        Record that a memory file was accessed (e.g., during recall).
+
+        Args:
+            path: File path relative to current/
+            commit: Commit hash at time of access
+            timestamp: ISO 8601 timestamp (default: now)
+        """
+        data = self._load()
+        ts = timestamp or datetime.utcnow().isoformat() + "Z"
+        data["access_log"].append({"path": path, "commit": commit, "timestamp": ts})
+        self._trim_access_log_if_needed(data)
+        self._save()
+
+    def _trim_access_log_if_needed(self, data: Dict[str, Any]) -> None:
+        if len(data.get("access_log", [])) > ACCESS_LOG_MAX:
+            data["access_log"] = data["access_log"][-ACCESS_LOG_MAX:]
+
+    def get_access_count(self, path: Optional[str] = None, commit: Optional[str] = None) -> int:
+        """
+        Get access count for a path and/or commit.
+
+        Args:
+            path: Filter by path (None = any)
+            commit: Filter by commit (None = any)
+
+        Returns:
+            Number of matching access entries
+        """
+        data = self._load()
+        entries = data.get("access_log", [])
+        count = 0
+        for entry in entries:
+            if path is not None and entry.get("path") != path:
+                continue
+            if commit is not None and entry.get("commit") != commit:
+                continue
+            count += 1
+        return count
+
+    def get_recent_accesses(
+        self,
+        limit: int = 100,
+        path: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Get most recent access entries.
+
+        Args:
+            limit: Max entries to return
+            path: Filter by path (None = any)
+
+        Returns:
+            List of access entries (newest first)
+        """
+        data = self._load()
+        entries = data.get("access_log", [])
+        if path is not None:
+            entries = [e for e in entries if e.get("path") == path]
+        return list(reversed(entries[-limit:]))
+
+    def get_access_counts_by_path(self) -> Dict[str, int]:
+        """Aggregate access counts per path (for importance weighting)."""
+        data = self._load()
+        counts: Dict[str, int] = {}
+        for entry in data.get("access_log", []):
+            p = entry.get("path", "")
+            counts[p] = counts.get(p, 0) + 1
+        return counts
+
+    def get_cache_key(self, context: str, strategy: str, limit: int, exclude: List[str]) -> str:
+        """Compute cache key for recall results."""
+        payload = f"{context}|{strategy}|{limit}|{','.join(sorted(exclude))}"
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def get_cached_recall(
+        self,
+        context: str,
+        strategy: str,
+        limit: int,
+        exclude: List[str],
+    ) -> Optional[Dict[str, Any]]:
+        """Get cached recall results if available."""
+        key = self.get_cache_key(context, strategy, limit, exclude)
+        data = self._load()
+        cache = data.get("recall_cache", {})
+        return cache.get(key)
+
+    def set_cached_recall(
+        self,
+        context: str,
+        strategy: str,
+        limit: int,
+        exclude: List[str],
+        results: List[Dict[str, Any]],
+    ) -> None:
+        """Cache recall results."""
+        key = self.get_cache_key(context, strategy, limit, exclude)
+        data = self._load()
+        if "recall_cache" not in data:
+            data["recall_cache"] = {}
+        data["recall_cache"][key] = {
+            "results": results,
+            "cached_at": datetime.utcnow().isoformat() + "Z",
+        }
+        # Limit cache size
+        cache = data["recall_cache"]
+        if len(cache) > 100:
+            oldest = sorted(cache.items(), key=lambda x: x[1].get("cached_at", ""))[:50]
+            for k, _ in oldest:
+                del cache[k]
+        self._save()

memvcs/core/config_loader.py

@@ -13,6 +13,7 @@ from typing import Any, Dict, List, Optional
 
 try:
     import yaml
+
     YAML_AVAILABLE = True
 except ImportError:
     YAML_AVAILABLE = False
@@ -116,7 +117,8 @@ def _apply_gcs_credentials_path(config: Dict[str, Any], repo_root: Optional[Path
         config[CONFIG_CLOUD][CONFIG_CLOUD_GCS]["credentials_path"] = resolved
     else:
         config[CONFIG_CLOUD][CONFIG_CLOUD_GCS] = {
-            k: v for k, v in config[CONFIG_CLOUD][CONFIG_CLOUD_GCS].items()
+            k: v
+            for k, v in config[CONFIG_CLOUD][CONFIG_CLOUD_GCS].items()
             if k != "credentials_path"
         }
 

memvcs/core/consistency.py

@@ -0,0 +1,214 @@
+"""
+Consistency checker - belief consistency for agmem semantic memories.
+
+Extracts (subject, predicate, object) triples and detects logical contradictions.
+"""
+
+import re
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass, field
+
+from .constants import MEMORY_TYPES
+from .schema import FrontmatterParser
+
+
+@dataclass
+class Triple:
+    """A (subject, predicate, object) triple."""
+
+    subject: str
+    predicate: str
+    obj: str
+    confidence: float
+    source: str
+    line: int
+
+
+@dataclass
+class Contradiction:
+    """A detected contradiction."""
+
+    triple1: Triple
+    triple2: Triple
+    reason: str
+
+
+@dataclass
+class ConsistencyResult:
+    """Result of consistency check."""
+
+    valid: bool
+    contradictions: List[Contradiction] = field(default_factory=list)
+    triples: List[Triple] = field(default_factory=list)
+    files_checked: int = 0
+
+
+# Inverse predicate pairs (A likes B vs B disliked by A)
+INVERSE_PREDICATES = [
+    ("likes", "dislikes"),
+    ("prefers", "avoids"),
+    ("uses", "avoids"),
+    ("enables", "disables"),
+    ("true", "false"),
+]
+
+
+class ConsistencyChecker:
+    """Detects logical contradictions in semantic memories."""
+
+    def __init__(self, repo: Any, llm_provider: Optional[str] = None):
+        self.repo = repo
+        self.llm_provider = llm_provider
+        self.current_dir = repo.root / "current"
+
+    def _extract_triples_simple(self, content: str, source: str) -> List[Triple]:
+        """Simple heuristic extraction of triples from text."""
+        triples = []
+        for i, line in enumerate(content.splitlines(), 1):
+            line = line.strip()
+            if not line or line.startswith("#") or line.startswith("---"):
+                continue
+            # Pattern: "user prefers X", "user likes Y", "X uses Y"
+            m = re.search(r"(user|agent)\s+(prefers|likes|uses|avoids|dislikes)\s+(.+)", line, re.I)
+            if m:
+                subj, pred, obj = m.group(1), m.group(2), m.group(3).strip()
+                triples.append(
+                    Triple(
+                        subject=subj.lower(),
+                        predicate=pred.lower(),
+                        obj=obj[:100],
+                        confidence=0.6,
+                        source=source,
+                        line=i,
+                    )
+                )
+            # Pattern: "X is Y"
+            m = re.search(r"^(.+?)\s+is\s+(.+?)(?:\.|$)", line)
+            if m:
+                subj, obj = m.group(1).strip(), m.group(2).strip()
+                triples.append(
+                    Triple(
+                        subject=subj[:50],
+                        predicate="is",
+                        obj=obj[:100],
+                        confidence=0.5,
+                        source=source,
+                        line=i,
+                    )
+                )
+        return triples
+
+    def _extract_triples_llm(self, content: str, source: str) -> List[Triple]:
+        """Extract triples using LLM."""
+        try:
+            import openai
+
+            response = openai.chat.completions.create(
+                model="gpt-3.5-turbo",
+                messages=[
+                    {
+                        "role": "system",
+                        "content": "Extract factual statements as (subject, predicate, object) triples. "
+                        "One per line, format: SUBJECT | PREDICATE | OBJECT",
+                    },
+                    {"role": "user", "content": content[:3000]},
+                ],
+                max_tokens=500,
+            )
+            text = response.choices[0].message.content
+            triples = []
+            for i, line in enumerate(text.splitlines(), 1):
+                if "|" in line:
+                    parts = [p.strip() for p in line.split("|", 2)]
+                    if len(parts) >= 3:
+                        triples.append(
+                            Triple(
+                                subject=parts[0][:50],
+                                predicate=parts[1][:30],
+                                obj=parts[2][:100],
+                                confidence=0.8,
+                                source=source,
+                                line=i,
+                            )
+                        )
+            return triples
+        except Exception:
+            return []
+
+    def extract_triples(self, content: str, source: str, use_llm: bool = False) -> List[Triple]:
+        """Extract triples from content."""
+        if use_llm and self.llm_provider == "openai":
+            t = self._extract_triples_llm(content, source)
+            if t:
+                return t
+        return self._extract_triples_simple(content, source)
+
+    def _are_inverse(self, pred1: str, pred2: str) -> bool:
+        """Check if predicates are inverses."""
+        for a, b in INVERSE_PREDICATES:
+            if (pred1 == a and pred2 == b) or (pred1 == b and pred2 == a):
+                return True
+        return False
+
+    def _same_subject_object(self, t1: Triple, t2: Triple) -> bool:
+        """Check if triples refer to same subject and object."""
+        s1, o1 = t1.subject.lower(), t1.obj.lower()
+        s2, o2 = t2.subject.lower(), t2.obj.lower()
+        return (s1 == s2 and o1 == o2) or (s1 == o2 and o1 == s2)
+
+    def detect_contradictions(self, triples: List[Triple]) -> List[Contradiction]:
+        """Detect contradictions among triples."""
+        contradictions = []
+        for i, t1 in enumerate(triples):
+            for t2 in triples[i + 1 :]:
+                if self._same_subject_object(t1, t2) and self._are_inverse(
+                    t1.predicate, t2.predicate
+                ):
+                    contradictions.append(
+                        Contradiction(
+                            triple1=t1,
+                            triple2=t2,
+                            reason=f"{t1.predicate} vs {t2.predicate}",
+                        )
+                    )
+        return contradictions
+
+    def check(self, use_llm: bool = False) -> ConsistencyResult:
+        """Check consistency of semantic memories."""
+        triples = []
+        files_checked = 0
+
+        if not self.current_dir.exists():
+            return ConsistencyResult(valid=True, files_checked=0)
+
+        semantic_dir = self.current_dir / "semantic"
+        if not semantic_dir.exists():
+            return ConsistencyResult(valid=True, files_checked=0)
+
+        for f in semantic_dir.rglob("*.md"):
+            if not f.is_file():
+                continue
+            try:
+                rel = str(f.relative_to(self.current_dir))
+                content = f.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                continue
+            files_checked += 1
+            triples.extend(self.extract_triples(content, rel, use_llm))
+
+        contradictions = self.detect_contradictions(triples)
+        return ConsistencyResult(
+            valid=len(contradictions) == 0,
+            contradictions=contradictions,
+            triples=triples,
+            files_checked=files_checked,
+        )
+
+    def repair(self, strategy: str = "confidence") -> ConsistencyResult:
+        """Attempt to auto-fix contradictions using strategy."""
+        result = self.check(use_llm=(strategy == "llm"))
+        if result.valid:
+            return result
+        # For now, repair just reports - actual fix would modify files
+        return result

memvcs/core/decay.py

@@ -0,0 +1,185 @@
+"""
+Decay engine - memory decay and forgetting for agmem.
+
+Mimics human forgetting: irrelevant details fade, important ones strengthen.
+Ebbinghaus-inspired time decay + retrieval-induced enhancement.
+"""
+
+import math
+import shutil
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+
+from .constants import MEMORY_TYPES
+from .access_index import AccessIndex
+from .objects import Commit
+from .schema import FrontmatterParser
+
+
+@dataclass
+class DecayConfig:
+    """Configuration for decay engine."""
+
+    episodic_half_life_days: int = 30
+    semantic_min_importance: float = 0.3
+    access_count_threshold: int = 2
+    forgetting_dir: str = "forgetting"
+
+
+@dataclass
+class DecayCandidate:
+    """A memory candidate for decay (archiving)."""
+
+    path: str
+    memory_type: str
+    importance: float
+    last_access_days: Optional[float]
+    access_count: int
+    decay_score: float
+    reason: str
+
+
+class DecayEngine:
+    """Computes decay scores and archives low-importance memories."""
+
+    def __init__(self, repo: Any, config: Optional[DecayConfig] = None):
+        self.repo = repo
+        self.config = config or DecayConfig()
+        self.access_index = AccessIndex(repo.mem_dir)
+        self.forgetting_dir = repo.mem_dir / self.config.forgetting_dir
+        self.current_dir = repo.current_dir
+
+    def _get_importance(self, path: str, content: str) -> float:
+        """Get importance from frontmatter or default."""
+        fm, _ = FrontmatterParser.parse(content)
+        if fm and fm.importance is not None:
+            return float(fm.importance)
+        if fm and fm.confidence_score is not None:
+            return float(fm.confidence_score)
+        return 0.5
+
+    def _get_access_info(self, path: str) -> Tuple[int, Optional[float]]:
+        """Get access count and days since last access."""
+        counts = self.access_index.get_access_counts_by_path()
+        count = counts.get(path, 0)
+        recent = self.access_index.get_recent_accesses(limit=1, path=path)
+        if not recent:
+            return count, None
+        ts_str = recent[0].get("timestamp", "")
+        if not ts_str:
+            return count, None
+        try:
+            if ts_str.endswith("Z"):
+                ts_str = ts_str[:-1] + "+00:00"
+            last = datetime.fromisoformat(ts_str)
+            days = (datetime.utcnow() - last.replace(tzinfo=None)).total_seconds() / 86400
+            return count, days
+        except Exception:
+            return count, None
+
+    def compute_decay_score(
+        self,
+        path: str,
+        content: str,
+        memory_type: str,
+    ) -> DecayCandidate:
+        """
+        Compute decay score for a memory.
+
+        Higher score = more likely to decay (archive).
+        Time decay: importance * 0.5^(days/half_life) when never accessed.
+        Retrieval-induced enhancement: access boosts strength (lower decay).
+        """
+        importance = self._get_importance(path, content)
+        access_count, last_access_days = self._get_access_info(path)
+
+        decay_score = 0.0
+        reason = ""
+
+        if "episodic" in memory_type.lower():
+            half_life = self.config.episodic_half_life_days
+            if last_access_days is not None:
+                decay_score = 1.0 - (importance * math.pow(0.5, last_access_days / half_life))
+                if access_count < self.config.access_count_threshold:
+                    decay_score += 0.2
+                reason = f"episodic: {last_access_days:.0f}d since access, imp={importance:.2f}"
+            else:
+                decay_score = 0.5
+                reason = "episodic: never accessed"
+        else:
+            if importance < self.config.semantic_min_importance:
+                decay_score = 1.0 - importance
+                reason = f"semantic: low importance {importance:.2f}"
+            elif (
+                access_count < self.config.access_count_threshold
+                and last_access_days
+                and last_access_days > 60
+            ):
+                decay_score = 0.4
+                reason = "semantic: rarely accessed"
+
+        return DecayCandidate(
+            path=path,
+            memory_type=memory_type,
+            importance=importance,
+            last_access_days=last_access_days,
+            access_count=access_count,
+            decay_score=decay_score,
+            reason=reason,
+        )
+
+    def get_decay_candidates(self) -> List[DecayCandidate]:
+        """Get list of memories that would be archived (dry-run)."""
+        candidates = []
+        if not self.current_dir.exists():
+            return candidates
+
+        for subdir in MEMORY_TYPES:
+            dir_path = self.current_dir / subdir
+            if not dir_path.exists():
+                continue
+            for f in dir_path.rglob("*"):
+                if not f.is_file() or f.suffix.lower() not in (".md", ".txt"):
+                    continue
+                try:
+                    rel_path = str(f.relative_to(self.current_dir))
+                    content = f.read_text(encoding="utf-8", errors="replace")
+                except Exception:
+                    continue
+                cand = self.compute_decay_score(rel_path, content, subdir)
+                if cand.decay_score > 0.5:
+                    candidates.append(cand)
+
+        candidates.sort(key=lambda x: x.decay_score, reverse=True)
+        return candidates
+
+    def apply_decay(self, candidates: Optional[List[DecayCandidate]] = None) -> int:
+        """
+        Archive low-importance memories to .mem/forgetting/.
+
+        Returns count of files archived.
+        """
+        if candidates is None:
+            candidates = self.get_decay_candidates()
+        self.forgetting_dir.mkdir(parents=True, exist_ok=True)
+        ts = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+        archive_sub = self.forgetting_dir / ts
+        archive_sub.mkdir(exist_ok=True)
+        count = 0
+        for cand in candidates:
+            if cand.decay_score <= 0.5:
+                continue
+            src = self.current_dir / cand.path
+            if not src.exists():
+                continue
+            try:
+                safe_name = cand.path.replace("/", "_").replace("..", "_")
+                dest = (archive_sub / safe_name).resolve()
+                dest.relative_to(self.forgetting_dir.resolve())
+                shutil.move(str(src), str(dest))
+                count += 1
+            except (ValueError, Exception):
+                continue
+        return count