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

memvcs/core/federated.py

@@ -0,0 +1,86 @@
+"""
+Federated memory collaboration for agmem.
+
+Agents share model updates or aggregated summaries instead of raw episodic logs.
+Optional coordinator URL; optional differential privacy (Tier 3).
+"""
+
+import json
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+from .config_loader import load_agmem_config
+
+
+def get_federated_config(repo_root: Path) -> Optional[Dict[str, Any]]:
+    """Get federated config from repo/user config. Returns None if disabled."""
+    config = load_agmem_config(repo_root)
+    fed = config.get("federated") or {}
+    if not fed.get("enabled"):
+        return None
+    url = fed.get("coordinator_url")
+    if not url:
+        return None
+    return {
+        "coordinator_url": url.rstrip("/"),
+        "memory_types": fed.get("memory_types", ["episodic", "semantic"]),
+    }
+
+
+def produce_local_summary(repo_root: Path, memory_types: List[str]) -> Dict[str, Any]:
+    """
+    Produce a local summary from episodic/semantic data (no raw content).
+    Returns dict suitable for sending to coordinator (e.g. topic counts, fact hashes).
+    """
+    current_dir = repo_root / "current"
+    summary = {"memory_types": memory_types, "topics": {}, "fact_count": 0}
+    for mtype in memory_types:
+        d = current_dir / mtype
+        if not d.exists():
+            continue
+        count = 0
+        for f in d.rglob("*.md"):
+            if f.is_file():
+                count += 1
+        summary["topics"][mtype] = count
+        if mtype == "semantic":
+            summary["fact_count"] = count
+    return summary
+
+
+def push_updates(repo_root: Path, summary: Dict[str, Any]) -> str:
+    """Send local summary to coordinator. Returns status message."""
+    cfg = get_federated_config(repo_root)
+    if not cfg:
+        return "Federated collaboration not configured"
+    url = cfg["coordinator_url"] + "/push"
+    try:
+        import urllib.request
+
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(summary).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            if resp.status in (200, 201):
+                return "Pushed updates to coordinator"
+            return f"Coordinator returned {resp.status}"
+    except Exception as e:
+        return f"Push failed: {e}"
+
+
+def pull_merged(repo_root: Path) -> Optional[Dict[str, Any]]:
+    """Pull merged summaries from coordinator. Returns merged data or None."""
+    cfg = get_federated_config(repo_root)
+    if not cfg:
+        return None
+    url = cfg["coordinator_url"] + "/pull"
+    try:
+        import urllib.request
+
+        with urllib.request.urlopen(url, timeout=30) as resp:
+            return json.loads(resp.read().decode())
+    except Exception:
+        return None

memvcs/core/gardener.py

@@ -284,37 +284,36 @@ class Gardener:
 
         combined = "\n---\n".join(contents)
 
-        # Try LLM summarization
-        if self.config.llm_provider == "openai" and self.config.llm_model:
+        # Try LLM summarization (multi-provider)
+        if self.config.llm_provider and self.config.llm_model:
             try:
-                return self._summarize_with_openai(combined, cluster.topic)
+                from .llm import get_provider
+
+                config = {
+                    "llm_provider": self.config.llm_provider,
+                    "llm_model": self.config.llm_model,
+                }
+                provider = get_provider(config=config)
+                if provider:
+                    return provider.complete(
+                        [
+                            {
+                                "role": "system",
+                                "content": "You are a helpful assistant that summarizes conversation logs into actionable insights.",
+                            },
+                            {
+                                "role": "user",
+                                "content": f"Summarize these conversation logs about '{cluster.topic}' into 2-3 key insights:\n\n{combined[:4000]}",
+                            },
+                        ],
+                        max_tokens=500,
+                    )
             except Exception:
                 pass
 
         # Fall back to simple summary
         return self._simple_summary(cluster, contents)
 
-    def _summarize_with_openai(self, content: str, topic: str) -> str:
-        """Summarize using OpenAI API."""
-        import openai
-
-        response = openai.chat.completions.create(
-            model=self.config.llm_model or "gpt-3.5-turbo",
-            messages=[
-                {
-                    "role": "system",
-                    "content": "You are a helpful assistant that summarizes conversation logs into actionable insights.",
-                },
-                {
-                    "role": "user",
-                    "content": f"Summarize these conversation logs about '{topic}' into 2-3 key insights:\n\n{content[:4000]}",
-                },
-            ],
-            max_tokens=500,
-        )
-
-        return response.choices[0].message.content
-
     def _simple_summary(self, cluster: EpisodeCluster, contents: List[str]) -> str:
         """Generate a simple summary without LLM."""
         return f"""# Insights: {cluster.topic.title()}

memvcs/core/ipfs_remote.py

@@ -0,0 +1,39 @@
+"""
+IPFS remote for agmem (stub).
+
+Push/pull via CIDs; pinning; gateway fallback when daemon unavailable.
+Requires optional ipfs extra (ipfshttpclient or gateway requests).
+"""
+
+from pathlib import Path
+from typing import Optional, Set
+
+from .objects import ObjectStore
+from .remote import _collect_objects_from_commit
+
+
+def push_to_ipfs(
+    objects_dir: Path,
+    branch: str,
+    commit_hash: str,
+    gateway_url: str = "https://ipfs.io",
+) -> Optional[str]:
+    """Push branch objects to IPFS and return root CID. Stub: returns None until IPFS client added."""
+    return None
+
+
+def pull_from_ipfs(
+    objects_dir: Path,
+    cid: str,
+    gateway_url: str = "https://ipfs.io",
+) -> bool:
+    """Pull objects by CID from IPFS into objects_dir. Stub: returns False until IPFS client added."""
+    return False
+
+
+def parse_ipfs_url(url: str) -> Optional[str]:
+    """Parse ipfs://<cid> or ipfs://<cid>/path. Returns CID or None."""
+    if not url.startswith("ipfs://"):
+        return None
+    rest = url[7:].lstrip("/")
+    return rest.split("/")[0] or None

memvcs/core/knowledge_graph.py

@@ -84,6 +84,7 @@ class KnowledgeGraphBuilder:
     1. Wikilinks: [[filename]] references
     2. Semantic similarity: Using embeddings
     3. Shared tags: Files with common tags
+    4. Co-occurrence: Facts in same episodic session (optional)
     """
 
     # Pattern for wikilinks: [[target]] or [[target|display text]]

memvcs/core/llm/__init__.py

@@ -0,0 +1,10 @@
+"""
+Multi-provider LLM integration for agmem.
+
+Abstract interface; implementations: OpenAI, Anthropic, Ollama, custom HTTP.
+"""
+
+from .base import LLMProvider
+from .factory import get_provider
+
+__all__ = ["LLMProvider", "get_provider"]

memvcs/core/llm/anthropic_provider.py

@@ -0,0 +1,50 @@
+"""Anthropic (Claude) LLM provider."""
+
+import os
+from typing import Optional, List, Dict, Any
+
+from .base import LLMProvider
+
+
+class AnthropicProvider(LLMProvider):
+    """Anthropic Claude provider. API key from ANTHROPIC_API_KEY."""
+
+    def __init__(self, model: Optional[str] = None):
+        self._model = model or os.environ.get("ANTHROPIC_MODEL", "claude-3-haiku-20240307")
+
+    @property
+    def name(self) -> str:
+        return "anthropic"
+
+    def complete(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        model: Optional[str] = None,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> str:
+        try:
+            import anthropic
+        except ImportError:
+            raise RuntimeError("Anthropic provider requires: pip install anthropic")
+        m = model or self._model
+        client = anthropic.Anthropic()
+        # Convert OpenAI-style messages to Anthropic (system + user/assistant)
+        system = ""
+        anthropic_messages = []
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                system = content
+            else:
+                anthropic_messages.append({"role": role, "content": content})
+        resp = client.messages.create(
+            model=m,
+            max_tokens=max_tokens,
+            system=system or None,
+            messages=anthropic_messages,
+            **kwargs,
+        )
+        return resp.content[0].text if resp.content else ""

memvcs/core/llm/base.py

@@ -0,0 +1,27 @@
+"""
+LLM provider interface for agmem.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, List, Dict, Any
+
+
+class LLMProvider(ABC):
+    """Abstract LLM provider (complete(messages) -> text)."""
+
+    @abstractmethod
+    def complete(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        model: Optional[str] = None,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> str:
+        """Return completion text for messages. Raises on failure."""
+        pass
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. openai, anthropic)."""
+        return "base"

memvcs/core/llm/factory.py

@@ -0,0 +1,30 @@
+"""LLM provider factory: select by config or env."""
+
+import os
+from typing import Optional, Dict, Any
+
+from .base import LLMProvider
+from .openai_provider import OpenAIProvider
+from .anthropic_provider import AnthropicProvider
+
+
+def get_provider(
+    provider_name: Optional[str] = None,
+    model: Optional[str] = None,
+    config: Optional[Dict[str, Any]] = None,
+) -> Optional[LLMProvider]:
+    """
+    Return LLM provider by name. Config may have llm_provider, llm_model.
+    Env: AGMEM_LLM_PROVIDER, OPENAI_API_KEY, ANTHROPIC_API_KEY.
+    """
+    name = (
+        provider_name
+        or (config or {}).get("llm_provider")
+        or os.environ.get("AGMEM_LLM_PROVIDER", "openai")
+    )
+    m = model or (config or {}).get("llm_model")
+    if name == "openai":
+        return OpenAIProvider(model=m)
+    if name == "anthropic":
+        return AnthropicProvider(model=m)
+    return OpenAIProvider(model=m)

memvcs/core/llm/openai_provider.py

@@ -0,0 +1,36 @@
+"""OpenAI LLM provider."""
+
+import os
+from typing import Optional, List, Dict, Any
+
+from .base import LLMProvider
+
+
+class OpenAIProvider(LLMProvider):
+    """OpenAI (GPT) provider. API key from OPENAI_API_KEY."""
+
+    def __init__(self, model: Optional[str] = None):
+        self._model = model or os.environ.get("OPENAI_MODEL", "gpt-3.5-turbo")
+
+    @property
+    def name(self) -> str:
+        return "openai"
+
+    def complete(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        model: Optional[str] = None,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> str:
+        import openai
+
+        m = model or self._model
+        response = openai.chat.completions.create(
+            model=m,
+            messages=messages,
+            max_tokens=max_tokens,
+            **kwargs,
+        )
+        return response.choices[0].message.content or ""

memvcs/core/merge.py

@@ -33,6 +33,8 @@ class Conflict:
     ours_content: Optional[str]
     theirs_content: Optional[str]
     message: str
+    memory_type: Optional[str] = None  # episodic, semantic, procedural
+    payload: Optional[Dict[str, Any]] = None  # type-specific (e.g. fact strings, step diffs)
 
 
 @dataclass
@@ -256,31 +258,31 @@ class MergeEngine:
         ours_content: Optional[str],
         theirs_content: Optional[str],
     ) -> Tuple[str, bool]:
-        """LLM arbitration: call LLM to resolve contradiction."""
+        """LLM arbitration: call LLM to resolve contradiction (multi-provider)."""
         try:
-            import openai
-
-            response = openai.chat.completions.create(
-                model="gpt-3.5-turbo",
-                messages=[
-                    {
-                        "role": "system",
-                        "content": "Resolve the contradiction between two memory versions. "
-                        "Output the merged content that best reflects the combined truth.",
-                    },
-                    {
-                        "role": "user",
-                        "content": f"OURS:\n{ours_content}\n\nTHEIRS:\n{theirs_content}",
-                    },
-                ],
-                max_tokens=1000,
-            )
-            merged = response.choices[0].message.content.strip()
-            return merged, False
+            from .llm import get_provider
+
+            provider = get_provider()
+            if provider:
+                merged = provider.complete(
+                    [
+                        {
+                            "role": "system",
+                            "content": "Resolve the contradiction between two memory versions. Output the merged content that best reflects the combined truth.",
+                        },
+                        {
+                            "role": "user",
+                            "content": f"OURS:\n{ours_content}\n\nTHEIRS:\n{theirs_content}",
+                        },
+                    ],
+                    max_tokens=1000,
+                )
+                return (merged or "").strip(), False
         except Exception:
-            # Fallback to conflict markers
-            merged = f"<<<<<<< OURS\n{ours_content}\n=======\n{theirs_content}\n>>>>>>> THEIRS"
-            return merged, True
+            pass
+        # Fallback to conflict markers
+        merged = f"<<<<<<< OURS\n{ours_content}\n=======\n{theirs_content}\n>>>>>>> THEIRS"
+        return merged, True
 
     def merge_procedural(
         self,
@@ -398,6 +400,15 @@ class MergeEngine:
 
             # Record conflict if any
             if had_conflict:
+                payload = {}
+                if ours_content:
+                    payload["ours_preview"] = (
+                        ours_content[:300] if len(ours_content) > 300 else ours_content
+                    )
+                if theirs_content:
+                    payload["theirs_preview"] = (
+                        theirs_content[:300] if len(theirs_content) > 300 else theirs_content
+                    )
                 conflicts.append(
                     Conflict(
                         path=path,
@@ -405,6 +416,8 @@ class MergeEngine:
                         ours_content=ours_content,
                         theirs_content=theirs_content,
                         message=f"{strategy.value} merge conflict in {path}",
+                        memory_type=strategy.value,
+                        payload=payload or None,
                     )
                 )
 

memvcs/core/objects.py

@@ -24,8 +24,9 @@ def _valid_object_hash(hash_id: str) -> bool:
 class ObjectStore:
     """Content-addressable object storage system."""
 
-    def __init__(self, objects_dir: Path):
+    def __init__(self, objects_dir: Path, encryptor: Optional[Any] = None):
         self.objects_dir = Path(objects_dir)
+        self._encryptor = encryptor
         self._ensure_directories()
 
     def _ensure_directories(self):
@@ -68,11 +69,15 @@ class ObjectStore:
         # Create directory if needed
         obj_path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Compress and store
+        # Compress and optionally encrypt
         header = f"{obj_type} {len(content)}\0".encode()
         full_content = header + content
         compressed = zlib.compress(full_content)
-
+        if self._encryptor:
+            try:
+                compressed = self._encryptor.encrypt_payload(compressed)
+            except ValueError:
+                pass  # no key; store plain compressed (legacy behavior)
         obj_path.write_bytes(compressed)
         return hash_id
 
@@ -92,9 +97,14 @@ class ObjectStore:
         if not obj_path.exists():
             return None
 
-        # Decompress and extract content
-        compressed = obj_path.read_bytes()
-        full_content = zlib.decompress(compressed)
+        raw = obj_path.read_bytes()
+        # Optionally decrypt (iv+tag minimum 12+16 bytes)
+        if self._encryptor and len(raw) >= 12 + 16:
+            try:
+                raw = self._encryptor.decrypt_payload(raw)
+            except Exception:
+                pass  # legacy plain compressed
+        full_content = zlib.decompress(raw)
 
         # Parse header
         null_idx = full_content.index(b"\0")

memvcs/core/pack.py

@@ -0,0 +1,92 @@
+"""
+Pack files and garbage collection for agmem.
+
+Pack: collect loose objects into single file + index. GC: delete unreachable objects, repack.
+"""
+
+import json
+import zlib
+from pathlib import Path
+from typing import Set, Dict, List, Optional, Tuple
+
+from .objects import ObjectStore
+from .refs import RefsManager
+
+
+def _pack_dir(objects_dir: Path) -> Path:
+    return objects_dir / "pack"
+
+
+def list_loose_objects(objects_dir: Path) -> Set[str]:
+    """List all loose object hashes (blob, tree, commit, tag)."""
+    hashes = set()
+    for obj_type in ["blob", "tree", "commit", "tag"]:
+        type_dir = objects_dir / obj_type
+        if not type_dir.exists():
+            continue
+        for prefix_dir in type_dir.iterdir():
+            if not prefix_dir.is_dir():
+                continue
+            for f in prefix_dir.iterdir():
+                hash_id = prefix_dir.name + f.name
+                hashes.add(hash_id)
+    return hashes
+
+
+def reachable_from_refs(mem_dir: Path, store: ObjectStore, gc_prune_days: int = 90) -> Set[str]:
+    """Collect all object hashes reachable from branches, tags, and reflog (within prune window)."""
+    refs = RefsManager(mem_dir)
+    reachable = set()
+    # Branch tips
+    for b in refs.list_branches():
+        ch = refs.get_branch_commit(b)
+        if ch:
+            reachable.update(_collect_from_commit(store, ch))
+    # Tags
+    for t in refs.list_tags():
+        ch = refs.get_tag_commit(t)
+        if ch:
+            reachable.update(_collect_from_commit(store, ch))
+    # Reflog (simplified: just HEAD recent)
+    try:
+        log = refs.get_reflog("HEAD", max_count=1000)
+        for e in log:
+            h = e.get("hash")
+            if h:
+                reachable.update(_collect_from_commit(store, h))
+    except Exception:
+        pass
+    return reachable
+
+
+def _collect_from_commit(store: ObjectStore, commit_hash: str) -> Set[str]:
+    """Collect all object hashes reachable from a commit."""
+    from .remote import _collect_objects_from_commit
+
+    return _collect_objects_from_commit(store, commit_hash)
+
+
+def run_gc(
+    mem_dir: Path, store: ObjectStore, gc_prune_days: int = 90, dry_run: bool = False
+) -> Tuple[int, int]:
+    """
+    Garbage collect: delete unreachable loose objects.
+    Returns (deleted_count, bytes_freed). dry_run: only report, do not delete.
+    """
+    loose = list_loose_objects(mem_dir / "objects")
+    reachable = reachable_from_refs(mem_dir, store, gc_prune_days)
+    to_delete = loose - reachable
+    freed = 0
+    for hash_id in to_delete:
+        # Resolve type from path
+        for obj_type in ["blob", "tree", "commit", "tag"]:
+            p = store.objects_dir / obj_type / hash_id[:2] / hash_id[2:]
+            if p.exists():
+                if not dry_run:
+                    size = p.stat().st_size
+                    p.unlink()
+                    freed += size
+                else:
+                    freed += p.stat().st_size
+                break
+    return (len(to_delete), freed)

memvcs/core/privacy_budget.py

@@ -0,0 +1,63 @@
+"""
+Differential privacy budget tracking for agmem.
+
+Per-repo epsilon spent; block when budget exceeded.
+"""
+
+import json
+import math
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def _budget_path(mem_dir: Path) -> Path:
+    return mem_dir / "privacy_budget.json"
+
+
+def load_budget(mem_dir: Path) -> Tuple[float, float, float]:
+    """Load (epsilon_spent, max_epsilon, delta). Returns (0, max, delta) if no file."""
+    path = _budget_path(mem_dir)
+    if not path.exists():
+        config = mem_dir / "config.json"
+        max_eps = 1.0
+        delta = 1e-5
+        if config.exists():
+            try:
+                c = json.loads(config.read_text())
+                dp = c.get("differential_privacy", {})
+                max_eps = float(dp.get("max_epsilon", 1.0))
+                delta = float(dp.get("delta", 1e-5))
+            except Exception:
+                pass
+        return (0.0, max_eps, delta)
+    try:
+        data = json.loads(path.read_text())
+        return (
+            float(data.get("epsilon_spent", 0)),
+            float(data.get("max_epsilon", 1.0)),
+            float(data.get("delta", 1e-5)),
+        )
+    except Exception:
+        return (0.0, 1.0, 1e-5)
+
+
+def spend_epsilon(mem_dir: Path, epsilon: float, max_epsilon: Optional[float] = None) -> bool:
+    """Record epsilon spent. Returns False if budget would be exceeded."""
+    spent, max_eps, delta = load_budget(mem_dir)
+    if max_epsilon is not None:
+        max_eps = max_epsilon
+    if spent + epsilon > max_eps:
+        return False
+    mem_dir.mkdir(parents=True, exist_ok=True)
+    path = _budget_path(mem_dir)
+    data = {"epsilon_spent": spent + epsilon, "max_epsilon": max_eps, "delta": delta}
+    path.write_text(json.dumps(data, indent=2))
+    return True
+
+
+def add_noise(value: float, sensitivity: float, epsilon: float, delta: float = 1e-5) -> float:
+    """Add Gaussian noise for (epsilon, delta)-DP. sigma = sensitivity * sqrt(2*ln(1.25/delta)) / epsilon."""
+    import random
+
+    sigma = sensitivity * math.sqrt(2 * math.log(1.25 / delta)) / epsilon
+    return value + random.gauss(0, sigma)