agmem 0.1.6__py3-none-any.whl → 0.2.1__py3-none-any.whl

memvcs/core/protocol_builder.py

@@ -0,0 +1,198 @@
+"""
+Protocol Builder for federated agent summaries.
+
+Ensures client-side summaries conform to the server's PushRequest schema
+before transmission, preventing 422 Validation Errors and protocol mismatches.
+
+Provides:
+- ClientSummaryBuilder: Constructs AgentSummary from raw produce_local_summary output
+- SchemaValidationError: Raised when summary doesn't match server schema
+- Deterministic agent_id generation from repository content
+"""
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class SchemaValidationError(Exception):
+    """Raised when client summary doesn't match server schema."""
+
+    pass
+
+
+class ClientSummaryBuilder:
+    """Build protocol-compliant AgentSummary from raw produce_local_summary output.
+
+    Handles:
+    - Key name mapping (topics -> topic_counts)
+    - Fact count to fact_hashes conversion (int -> list of hash strings)
+    - Auto-generation of agent_id from repo hash (deterministic, replayable)
+    - ISO-8601 timestamp addition
+    - Schema validation against server expectations
+    - Wrapping in {"summary": {...}} envelope
+    """
+
+    REQUIRED_FIELDS = {"agent_id", "timestamp", "topic_counts", "fact_hashes"}
+
+    @staticmethod
+    def generate_agent_id(repo_root: Path) -> str:
+        """Generate deterministic agent_id from repository content.
+
+        Uses SHA-256 hash of repo root path to ensure consistency across runs
+        while remaining unique per repository. This is deterministic (same repo
+        always gets same agent_id) and replayable.
+
+        Args:
+            repo_root: Path to the repository root
+
+        Returns:
+            Unique agent identifier in format: "agent-<first-16-chars-of-hash>"
+        """
+        repo_hash = hashlib.sha256(str(repo_root.resolve()).encode()).hexdigest()[:16]
+        return f"agent-{repo_hash}"
+
+    @staticmethod
+    def build(
+        repo_root: Path,
+        raw_summary: Dict[str, Any],
+        strict_mode: bool = False,
+    ) -> Dict[str, Any]:
+        """Build protocol-compliant summary from raw produce_local_summary output.
+
+        Transforms the client's produce_local_summary() output into the format
+        expected by the server's PushRequest model.
+
+        Args:
+            repo_root: Path to repository root (used for agent_id generation)
+            raw_summary: Output from produce_local_summary()
+            strict_mode: If True, raise on validation error; if False, warn and repair
+
+        Returns:
+            Dict with structure: {"summary": {"agent_id": "...", "timestamp": "...",
+                                              "topic_counts": {...}, "fact_hashes": [...]}}
+
+        Raises:
+            SchemaValidationError: If strict_mode=True and schema validation fails
+        """
+        # In strict mode, validate raw input has required fields BEFORE transformation
+        if strict_mode:
+            required_raw_fields = {"memory_types", "topics", "topic_hashes", "fact_count"}
+            missing = required_raw_fields - set(raw_summary.keys())
+            if missing:
+                raise SchemaValidationError(
+                    f"Raw summary missing required fields: {', '.join(sorted(missing))}"
+                )
+
+        # Generate required fields
+        agent_id = ClientSummaryBuilder.generate_agent_id(repo_root)
+        timestamp = datetime.now(timezone.utc).isoformat()
+
+        # Transform key names and structure
+        topic_counts = raw_summary.get("topics", {})
+        if not isinstance(topic_counts, dict):
+            topic_counts = {}
+
+        # Convert fact_count (int) to fact_hashes (list of strings)
+        # If topic_hashes is present, use it; otherwise generate from fact_count
+        fact_hashes: List[str] = []
+        if "topic_hashes" in raw_summary and isinstance(raw_summary["topic_hashes"], dict):
+            # Flatten all topic hashes into a single list
+            for topic_hash_list in raw_summary["topic_hashes"].values():
+                if isinstance(topic_hash_list, list):
+                    fact_hashes.extend(topic_hash_list)
+
+        # If fact_hashes is still empty but we have fact_count, generate placeholder hashes
+        if not fact_hashes and "fact_count" in raw_summary:
+            fact_count = raw_summary["fact_count"]
+            if isinstance(fact_count, int):
+                # Generate placeholder hashes (in real scenario, client would preserve actual hashes)
+                fact_hashes = [
+                    hashlib.sha256(f"fact-{i}".encode()).hexdigest() for i in range(fact_count)
+                ]
+
+        # Build AgentSummary structure
+        agent_summary = {
+            "agent_id": agent_id,
+            "timestamp": timestamp,
+            "topic_counts": topic_counts,
+            "fact_hashes": fact_hashes,
+        }
+
+        # Validate schema
+        errors = ClientSummaryBuilder._validate_schema(agent_summary)
+        if errors:
+            error_msg = f"Schema validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+            if strict_mode:
+                raise SchemaValidationError(error_msg)
+            else:
+                print(f"Warning: {error_msg}")
+
+        # Return wrapped in envelope
+        return {"summary": agent_summary}
+
+    @staticmethod
+    def _validate_schema(agent_summary: Dict[str, Any]) -> List[str]:
+        """Validate agent_summary against expected schema.
+
+        Args:
+            agent_summary: The summary dict to validate
+
+        Returns:
+            List of error messages (empty if valid)
+        """
+        errors = []
+
+        # Check required fields
+        for field in ClientSummaryBuilder.REQUIRED_FIELDS:
+            if field not in agent_summary:
+                errors.append(f"Missing required field: {field}")
+
+        # Validate field types
+        if "agent_id" in agent_summary and not isinstance(agent_summary["agent_id"], str):
+            errors.append(f"agent_id must be string, got {type(agent_summary['agent_id'])}")
+
+        if "timestamp" in agent_summary:
+            ts = agent_summary["timestamp"]
+            if not isinstance(ts, str):
+                errors.append(f"timestamp must be string, got {type(ts)}")
+            # Validate ISO-8601 format
+            elif not _is_iso8601(ts):
+                errors.append(f"timestamp not in ISO-8601 format: {ts}")
+
+        if "topic_counts" in agent_summary:
+            tc = agent_summary["topic_counts"]
+            if not isinstance(tc, dict):
+                errors.append(f"topic_counts must be dict, got {type(tc)}")
+            else:
+                for k, v in tc.items():
+                    if not isinstance(k, str):
+                        errors.append(f"topic_counts key must be string, got {type(k)}")
+                    if not isinstance(v, int):
+                        errors.append(f"topic_counts value must be int, got {type(v)}")
+
+        if "fact_hashes" in agent_summary:
+            fh = agent_summary["fact_hashes"]
+            if not isinstance(fh, list):
+                errors.append(f"fact_hashes must be list, got {type(fh)}")
+            else:
+                for h in fh:
+                    if not isinstance(h, str):
+                        errors.append(f"fact_hashes element must be string, got {type(h)}")
+
+        return errors
+
+
+def _is_iso8601(timestamp: str) -> bool:
+    """Check if timestamp is in ISO-8601 format."""
+    try:
+        # Try parsing with common ISO-8601 formats
+        if timestamp.endswith("Z"):
+            datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        else:
+            datetime.fromisoformat(timestamp)
+        return True
+    except (ValueError, TypeError):
+        return False

memvcs/core/remote.py

@@ -1,7 +1,7 @@
 """
-Remote sync for agmem - file-based and cloud (S3/GCS) push/pull/clone.
+Remote sync for agmem - file-based, cloud (S3/GCS), and IPFS push/pull/clone.
 
-Supports file:// URLs and s3:///gs:// with optional distributed locking.
+Supports file://, s3://, gs://, and ipfs:// URLs with optional distributed locking.
 """
 
 import json
@@ -19,6 +19,11 @@ def _is_cloud_remote(url: str) -> bool:
     return url.startswith("s3://") or url.startswith("gs://")
 
 
+def _is_ipfs_remote(url: str) -> bool:
+    """Return True if URL is IPFS (ipfs://<cid>)."""
+    return url.startswith("ipfs://")
+
+
 def parse_remote_url(url: str) -> Path:
     """Parse remote URL to local path. Supports file:// only. Rejects path traversal."""
     parsed = urlparse(url)
@@ -302,6 +307,75 @@ class Remote:
             pass
         return f"Fetched {copied} object(s) from {self.name}"
 
+    def _push_to_ipfs(self, branch: Optional[str] = None) -> str:
+        """Push objects to IPFS and update remote URL with CID."""
+        from .ipfs_remote import push_to_ipfs
+
+        refs = RefsManager(self.mem_dir)
+        store = ObjectStore(self.objects_dir)
+
+        # Determine which branch to push
+        target_branch = branch if branch else refs.get_current_branch() or "main"
+        commit_hash = refs.get_branch_commit(target_branch)
+
+        if not commit_hash:
+            raise ValueError(f"Branch '{target_branch}' has no commit")
+
+        # Get gateway URL from config or use default
+        gateway_url = self._config.get("ipfs", {}).get("gateway", "https://ipfs.io")
+
+        # Push to IPFS
+        cid = push_to_ipfs(self.objects_dir, target_branch, commit_hash, gateway_url, store)
+
+        if not cid:
+            raise ValueError("Failed to push to IPFS gateway")
+
+        # Update remote URL to new CID for future pulls
+        self.set_remote_url(f"ipfs://{cid}")
+
+        # TODO: Pin CID to prevent garbage collection
+        # Options: local IPFS daemon (ipfshttpclient), pinning service (Pinata/Infura)
+        # For now, user must manually pin or use a pinning service
+
+        try:
+            from .audit import append_audit
+
+            append_audit(
+                self.mem_dir,
+                "push",
+                {"remote": self.name, "branch": target_branch, "ipfs_cid": cid},
+            )
+        except Exception:
+            pass
+
+        return f"Pushed to IPFS: {cid} (WARNING: Not pinned - will be garbage collected unless pinned separately)"
+
+    def _pull_from_ipfs(self, url: str) -> str:
+        """Pull objects from IPFS by CID."""
+        from .ipfs_remote import pull_from_ipfs, parse_ipfs_url
+
+        cid = parse_ipfs_url(url)
+        if not cid:
+            raise ValueError(f"Invalid IPFS URL: {url}")
+
+        # Get gateway URL from config or use default
+        gateway_url = self._config.get("ipfs", {}).get("gateway", "https://ipfs.io")
+
+        # Pull from IPFS
+        success = pull_from_ipfs(self.objects_dir, cid, gateway_url)
+
+        if not success:
+            raise ValueError(f"Failed to pull from IPFS: {cid}")
+
+        try:
+            from .audit import append_audit
+
+            append_audit(self.mem_dir, "fetch", {"remote": self.name, "ipfs_cid": cid})
+        except Exception:
+            pass
+
+        return f"Fetched from IPFS: {cid}"
+
     def push(self, branch: Optional[str] = None) -> str:
         """
         Push objects and refs to remote.
@@ -311,6 +385,9 @@ class Remote:
         if not url:
             raise ValueError(f"Remote '{self.name}' has no URL configured")
 
+        if _is_ipfs_remote(url):
+            return self._push_to_ipfs(branch)
+
         if _is_cloud_remote(url):
             try:
                 from .storage import get_adapter
@@ -427,6 +504,9 @@ class Remote:
         if not url:
             raise ValueError(f"Remote '{self.name}' has no URL configured")
 
+        if _is_ipfs_remote(url):
+            return self._pull_from_ipfs(url)
+
         if _is_cloud_remote(url):
             try:
                 from .storage import get_adapter

memvcs/core/zk_proofs.py

@@ -1,5 +1,17 @@
 """
-Zero-knowledge proof system for agmem.
+Cryptographic proof system for agmem.
+
+IMPORTANT: Current implementation provides PROOF-OF-KNOWLEDGE, not true zero-knowledge proofs.
+
+Limitations:
+- Keyword proof leaks: word count in file, allows verifier to test other words
+- Freshness proof: relies on forgeable filesystem mtime
+- Both proofs reveal deterministic information about file content
+
+For true zero-knowledge proofs, consider integrating zk-SNARK libraries like:
+- py-ecc (Ethereum cryptography)
+- circom (circuit compiler)
+- libsnark bindings
 
 Hash/signature-based proofs: keyword containment (Merkle set membership),
 memory freshness (signed timestamp). Full zk-SNARK backend can be added later.
@@ -36,8 +48,30 @@ def _word_hashes(content: str) -> List[str]:
 
 def prove_keyword_containment(memory_path: Path, keyword: str, output_proof_path: Path) -> bool:
     """
-    Prove memory file contains keyword without revealing content.
-    Proof: Merkle set membership of H(keyword) over word hashes in file.
+    Prove memory file contains keyword using Merkle set membership.
+
+    WARNING: This is PROOF-OF-KNOWLEDGE, not zero-knowledge:
+    - Leaks exact count of unique words in file (via Merkle root)
+    - Verifier can test if OTHER words exist by hashing and checking against same root
+    - Root is deterministic over full word set
+
+    For true zero-knowledge, would need:
+    - Commitment scheme that hides set size
+    - zk-SNARK proof that keyword ∈ committed set
+    - No ability for verifier to test other words
+
+    Current implementation is useful for:
+    - Proving you possess a file containing specific keywords
+    - Auditing that memories contain required terms
+    - Not suitable for privacy-preserving keyword proofs
+
+    Args:
+        memory_path: Path to memory file
+        keyword: Keyword to prove containment of
+        output_proof_path: Where to write proof JSON
+
+    Returns:
+        True if proof created successfully
     """
     if not memory_path.exists() or not memory_path.is_file():
         return False
@@ -68,8 +102,31 @@ def prove_memory_freshness(
     memory_path: Path, after_timestamp: str, output_proof_path: Path, mem_dir: Optional[Path] = None
 ) -> bool:
     """
-    Prove memory was updated after date without revealing content.
-    Proof: signed file mtime (or current time) and optional public key.
+    Prove memory was updated after date using signed timestamp.
+
+    WARNING: Security limitations:
+    - Relies on filesystem mtime which is TRIVIALLY FORGEABLE (touch command)
+    - Only proves key holder signed *some* timestamp, not actual freshness
+    - No protection against backdating files
+
+    Improvements needed:
+    - Sign content hash + timestamp (not just timestamp)
+    - Use trusted timestamping service (RFC 3161)
+    - Blockchain-based timestamp anchoring
+
+    Current implementation is useful for:
+    - Proving you signed a file at some claimed time
+    - Creating audit trails with signature verification
+    - Not suitable for proving actual file recency
+
+    Args:
+        memory_path: Path to memory file
+        after_timestamp: Timestamp to prove freshness after (not currently enforced)
+        output_proof_path: Where to write proof JSON
+        mem_dir: Memory directory for key loading
+
+    Returns:
+        True if proof created successfully
     """
     if not memory_path.exists() or not memory_path.is_file():
         return False

memvcs/health/__init__.py

@@ -0,0 +1,25 @@
+"""Health monitoring module for agmem daemon."""
+
+from .monitor import (
+    HealthMonitor,
+    StorageMonitor,
+    SemanticRedundancyChecker,
+    StaleMemoryDetector,
+    GraphConsistencyValidator,
+    StorageMetrics,
+    RedundancyReport,
+    StaleMemoryReport,
+    GraphConsistencyReport,
+)
+
+__all__ = [
+    "HealthMonitor",
+    "StorageMonitor",
+    "SemanticRedundancyChecker",
+    "StaleMemoryDetector",
+    "GraphConsistencyValidator",
+    "StorageMetrics",
+    "RedundancyReport",
+    "StaleMemoryReport",
+    "GraphConsistencyReport",
+]