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

memvcs/core/vector_store.py

@@ -6,11 +6,11 @@ Requires: pip install agmem[vector]
 """
 
 import logging
+import struct
+from pathlib import Path
 from typing import List, Optional, Tuple
 
 from .constants import MEMORY_TYPES
-import struct
-from pathlib import Path
 
 logger = logging.getLogger("agmem.vector_store")
 
@@ -56,6 +56,19 @@ class VectorStore:
                 "On macOS, try: brew install python (for Homebrew SQLite)"
             ) from e
 
+    def _device(self) -> str:
+        """Return device for embeddings: cuda/mps/cpu. GPU acceleration when available."""
+        try:
+            import torch
+
+            if torch.cuda.is_available():
+                return "cuda"
+            if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+                return "mps"
+        except ImportError:
+            pass
+        return "cpu"
+
     def _get_model(self):
         """Lazy-load the sentence-transformers model."""
         if self._model is not None:
@@ -64,7 +77,8 @@ class VectorStore:
         try:
             from sentence_transformers import SentenceTransformer
 
-            self._model = SentenceTransformer("all-MiniLM-L6-v2")
+            device = self._device()
+            self._model = SentenceTransformer("all-MiniLM-L6-v2", device=device)
             return self._model
         except ImportError as e:
             raise ImportError(
@@ -75,7 +89,8 @@ class VectorStore:
     def _ensure_tables(self):
         """Create vector and metadata tables if they don't exist."""
         conn = self._get_connection()
-        conn.execute("""
+        conn.execute(
+            """
             CREATE TABLE IF NOT EXISTS memory_meta (
                 rowid INTEGER PRIMARY KEY,
                 path TEXT NOT NULL,
@@ -85,18 +100,21 @@ class VectorStore:
                 author TEXT,
                 indexed_at TEXT
             )
-        """)
+        """
+        )
         # Try to add new columns to existing tables (for upgrades)
-        for col in ['commit_hash TEXT', 'author TEXT', 'indexed_at TEXT']:
+        for col in ["commit_hash TEXT", "author TEXT", "indexed_at TEXT"]:
             try:
                 conn.execute(f"ALTER TABLE memory_meta ADD COLUMN {col}")
             except Exception:
                 pass  # Column already exists
         try:
-            conn.execute(f"""
+            conn.execute(
+                f"""
                 CREATE VIRTUAL TABLE IF NOT EXISTS vec_memory
                 USING vec0(embedding float[{EMBEDDING_DIM}])
-            """)
+            """
+            )
         except Exception as e:
             # vec0 might already exist with different schema
             logger.debug("vec_memory creation: %s", e)
@@ -114,11 +132,11 @@ class VectorStore:
         content: str,
         blob_hash: Optional[str] = None,
         commit_hash: Optional[str] = None,
-        author: Optional[str] = None
+        author: Optional[str] = None,
     ) -> None:
         """
         Index a memory file for semantic search.
-        
+
         Args:
             path: File path relative to current/
             content: File content to index
@@ -127,13 +145,13 @@ class VectorStore:
             author: Optional author string for provenance tracking
         """
         from datetime import datetime
-        
+
         self._ensure_tables()
         conn = self._get_connection()
 
         embedding = self._embed(content)
         emb_bytes = _serialize_f32(embedding)
-        indexed_at = datetime.utcnow().isoformat() + 'Z'
+        indexed_at = datetime.utcnow().isoformat() + "Z"
 
         with conn:
             conn.execute(
@@ -203,13 +221,13 @@ class VectorStore:
             results.append((path, snippet, float(distance)))
 
         return results
-    
+
     def search_with_provenance(
         self, query: str, limit: int = 10, min_score: Optional[float] = None
     ) -> List[dict]:
         """
         Semantic search with provenance metadata.
-        
+
         Returns list of dicts with: path, content, distance, commit_hash, author, indexed_at
         """
         self._ensure_tables()
@@ -235,51 +253,53 @@ class VectorStore:
             if min_score is not None and distance > min_score:
                 continue
             snippet = content[:500] + ("..." if len(content) > 500 else "")
-            results.append({
-                'path': path,
-                'content': snippet,
-                'distance': float(distance),
-                'similarity': 1.0 - float(distance),  # Convert to similarity score
-                'commit_hash': commit_hash,
-                'author': author,
-                'indexed_at': indexed_at,
-                'blob_hash': blob_hash
-            })
+            results.append(
+                {
+                    "path": path,
+                    "content": snippet,
+                    "distance": float(distance),
+                    "similarity": 1.0 - float(distance),  # Convert to similarity score
+                    "commit_hash": commit_hash,
+                    "author": author,
+                    "indexed_at": indexed_at,
+                    "blob_hash": blob_hash,
+                }
+            )
 
         return results
-    
+
     def get_all_entries(self) -> List[dict]:
         """
         Get all indexed entries with their metadata.
-        
+
         Used for fsck operations to check for dangling vectors.
         """
         self._ensure_tables()
         conn = self._get_connection()
-        
+
         rows = conn.execute(
             """
             SELECT rowid, path, blob_hash, commit_hash, author, indexed_at
             FROM memory_meta
             """
         ).fetchall()
-        
+
         return [
             {
-                'rowid': rowid,
-                'path': path,
-                'blob_hash': blob_hash,
-                'commit_hash': commit_hash,
-                'author': author,
-                'indexed_at': indexed_at
+                "rowid": rowid,
+                "path": path,
+                "blob_hash": blob_hash,
+                "commit_hash": commit_hash,
+                "author": author,
+                "indexed_at": indexed_at,
             }
             for rowid, path, blob_hash, commit_hash, author, indexed_at in rows
         ]
-    
+
     def delete_entry(self, rowid: int) -> bool:
         """
         Delete an entry by rowid.
-        
+
         Used by fsck to remove dangling vectors.
         """
         conn = self._get_connection()

memvcs/core/zk_proofs.py

@@ -0,0 +1,26 @@
+"""
+Zero-knowledge proof system for agmem (stub).
+
+Planned: zk-SNARKs (Groth16) for keyword containment, memory freshness, competence verification.
+Requires optional zk extra (circuit lib, proving system). Trusted setup: public ceremony or small multi-party.
+"""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def prove_keyword_containment(memory_path: Path, keyword: str, output_proof_path: Path) -> bool:
+    """Prove memory file contains keyword without revealing content. Stub: returns False until zk backend added."""
+    return False
+
+
+def prove_memory_freshness(
+    memory_path: Path, after_timestamp: str, output_proof_path: Path
+) -> bool:
+    """Prove memory was updated after date without revealing content. Stub: returns False until zk backend added."""
+    return False
+
+
+def verify_proof(proof_path: Path, statement_type: str, **kwargs) -> bool:
+    """Verify a zk proof. Stub: returns False until zk backend added."""
+    return False

memvcs/integrations/mcp_server.py

@@ -219,9 +219,7 @@ def _create_mcp_server():
                     fp = Path(root) / f
                     rel = str(fp.relative_to(repo.current_dir))
                     working_files[rel] = fp.read_bytes()
-            tree_diff = engine.diff_working_dir(
-                head_commit.store(repo.object_store), working_files
-            )
+            tree_diff = engine.diff_working_dir(head_commit.store(repo.object_store), working_files)
             return engine.format_diff(tree_diff, "HEAD", "working")
         else:
             base_ref = base or "HEAD~1"

memvcs/integrations/web_ui/server.py

@@ -50,7 +50,9 @@ def create_app(repo_path: Path) -> FastAPI:
         if not repo.is_valid_repo():
             raise HTTPException(status_code=400, detail="Not an agmem repository")
 
-        resolved = repo.resolve_ref(commit_hash) or (commit_hash if _valid_commit_hash(commit_hash) else None)
+        resolved = repo.resolve_ref(commit_hash) or (
+            commit_hash if _valid_commit_hash(commit_hash) else None
+        )
         if not resolved:
             raise HTTPException(status_code=400, detail="Invalid revision or hash")
         c = Commit.load(repo.object_store, resolved)
@@ -87,13 +89,15 @@ def create_app(repo_path: Path) -> FastAPI:
         tree_diff = engine.diff_commits(c1, c2)
         files = []
         for fd in tree_diff.files:
-            files.append({
-                "path": fd.path,
-                "diff_type": fd.diff_type.value,
-                "old_hash": fd.old_hash,
-                "new_hash": fd.new_hash,
-                "diff_lines": fd.diff_lines,
-            })
+            files.append(
+                {
+                    "path": fd.path,
+                    "diff_type": fd.diff_type.value,
+                    "old_hash": fd.old_hash,
+                    "new_hash": fd.new_hash,
+                    "diff_lines": fd.diff_lines,
+                }
+            )
         return {
             "base": base,
             "head": head,
@@ -138,37 +142,32 @@ def create_app(repo_path: Path) -> FastAPI:
         if include_similarity:
             try:
                 from memvcs.core.vector_store import VectorStore
-                vector_store = VectorStore(_repo_path / '.mem')
+
+                vector_store = VectorStore(_repo_path / ".mem")
             except ImportError:
                 pass
 
         builder = KnowledgeGraphBuilder(repo, vector_store)
         graph_data = builder.build_graph(
-            include_similarity=include_similarity,
-            similarity_threshold=threshold
+            include_similarity=include_similarity, similarity_threshold=threshold
         )
 
         # Return D3-compatible format
         return {
-            'nodes': [
+            "nodes": [
                 {
-                    'id': n.id,
-                    'name': n.label,
-                    'group': n.memory_type,
-                    'size': min(20, max(5, n.size // 100))
+                    "id": n.id,
+                    "name": n.label,
+                    "group": n.memory_type,
+                    "size": min(20, max(5, n.size // 100)),
                 }
                 for n in graph_data.nodes
             ],
-            'links': [
-                {
-                    'source': e.source,
-                    'target': e.target,
-                    'type': e.edge_type,
-                    'value': e.weight
-                }
+            "links": [
+                {"source": e.source, "target": e.target, "type": e.edge_type, "value": e.weight}
                 for e in graph_data.edges
             ],
-            'metadata': graph_data.metadata
+            "metadata": graph_data.metadata,
         }
 
     @app.get("/graph", response_class=HTMLResponse)
@@ -185,7 +184,7 @@ def create_app(repo_path: Path) -> FastAPI:
 
 
 # Embedded graph viewer template
-GRAPH_HTML_TEMPLATE = '''<!DOCTYPE html>
+GRAPH_HTML_TEMPLATE = """<!DOCTYPE html>
 <html>
 <head>
     <title>agmem Knowledge Graph</title>
@@ -349,4 +348,4 @@ GRAPH_HTML_TEMPLATE = '''<!DOCTYPE html>
     </script>
 </body>
 </html>
-'''
+"""

memvcs/retrieval/__init__.py

@@ -0,0 +1,22 @@
+"""
+Retrieval module for agmem - context-aware recall with pluggable strategies.
+"""
+
+from .base import RetrievalStrategy, RecallResult
+from .strategies import (
+    RecencyStrategy,
+    ImportanceStrategy,
+    SimilarityStrategy,
+    HybridStrategy,
+)
+from .recaller import RecallEngine
+
+__all__ = [
+    "RetrievalStrategy",
+    "RecallResult",
+    "RecencyStrategy",
+    "ImportanceStrategy",
+    "SimilarityStrategy",
+    "HybridStrategy",
+    "RecallEngine",
+]

memvcs/retrieval/base.py

@@ -0,0 +1,54 @@
+"""
+Base retrieval interfaces for agmem recall.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List, Any, Optional
+
+
+@dataclass
+class RecallResult:
+    """Single recalled memory with metadata."""
+
+    path: str
+    content: str
+    relevance_score: float
+    source: dict  # commit_hash, author, indexed_at, etc.
+    importance: Optional[float] = None
+
+    def to_dict(self) -> dict:
+        """Convert to JSON-serializable dict."""
+        return {
+            "path": self.path,
+            "content": self.content,
+            "relevance_score": self.relevance_score,
+            "source": self.source,
+            "importance": self.importance,
+        }
+
+
+class RetrievalStrategy(ABC):
+    """Abstract base for recall strategies."""
+
+    @abstractmethod
+    def recall(
+        self,
+        context: str,
+        limit: int,
+        exclude: List[str],
+        **kwargs: Any,
+    ) -> List[RecallResult]:
+        """
+        Retrieve and rank memories for the given context.
+
+        Args:
+            context: Current task description
+            limit: Max results to return
+            exclude: Tag/branch patterns to exclude (e.g., "experiment/*")
+            **kwargs: Strategy-specific options
+
+        Returns:
+            Ranked list of RecallResult
+        """
+        pass

memvcs/retrieval/pack.py

@@ -0,0 +1,128 @@
+"""
+Pack engine - context window budget manager for agmem.
+
+Fills token budget with most relevant memories, optionally with summarization cascade.
+"""
+
+from typing import List, Optional, Any
+from dataclasses import dataclass
+
+from .base import RecallResult
+from .recaller import RecallEngine
+
+
+@dataclass
+class PackResult:
+    """Result of packing memories into budget."""
+
+    content: str
+    total_tokens: int
+    budget: int
+    items_used: int
+    items_total: int
+
+
+class PackEngine:
+    """Packs recalled memories into a token budget."""
+
+    def __init__(
+        self,
+        recall_engine: RecallEngine,
+        model: str = "gpt-4o-mini",
+        summarization_cascade: bool = False,
+    ):
+        self.recall_engine = recall_engine
+        self.model = model
+        self.summarization_cascade = summarization_cascade
+
+    def _count_tokens(self, text: str) -> int:
+        """Count tokens using tiktoken."""
+        try:
+            import tiktoken
+
+            enc = tiktoken.encoding_for_model(self.model)
+            return len(enc.encode(text))
+        except ImportError:
+            # Fallback: ~4 chars per token
+            return len(text) // 4
+        except Exception:
+            return len(text) // 4
+
+    def pack(
+        self,
+        context: str,
+        budget: int = 4000,
+        strategy: str = "relevance",
+        exclude: Optional[List[str]] = None,
+    ) -> PackResult:
+        """
+        Pack memories into token budget.
+
+        Args:
+            context: Current task description for recall
+            budget: Max tokens to use
+            strategy: recall strategy (relevance=hybrid, recency, importance)
+            exclude: Path patterns to exclude
+
+        Returns:
+            PackResult with packed content and metadata
+        """
+        exclude = exclude or []
+        recall_strategy = "hybrid" if strategy == "relevance" else strategy
+        if recall_strategy not in ("hybrid", "recency", "importance", "similarity"):
+            recall_strategy = "hybrid"
+
+        results = self.recall_engine.recall(
+            context=context,
+            limit=50,  # Get more candidates
+            strategy=recall_strategy,
+            exclude=exclude,
+        )
+
+        # Sort by relevance (already sorted by recall)
+        # Add tokens, fill greedily
+        total_tokens = 0
+        packed_items: List[RecallResult] = []
+        separator = "\n\n---\n\n"
+        header = f"# Context for: {context}\n\n" if context else ""
+        header_tokens = self._count_tokens(header)
+        budget -= header_tokens
+
+        for r in results:
+            item_text = f"## {r.path}\n{r.content}"
+            item_tokens = self._count_tokens(item_text)
+            if total_tokens + item_tokens <= budget:
+                packed_items.append(r)
+                total_tokens += item_tokens
+            else:
+                # Try truncated
+                if total_tokens < budget and item_tokens > 0:
+                    ratio = (budget - total_tokens) / item_tokens
+                    if ratio > 0.2:  # At least 20% of item
+                        trunc_len = int(len(item_text) * ratio)
+                        truncated = item_text[:trunc_len] + "\n..."
+                        pack_tokens = self._count_tokens(truncated)
+                        if total_tokens + pack_tokens <= budget:
+                            r_trunc = RecallResult(
+                                path=r.path,
+                                content=r.content[: int(len(r.content) * ratio)] + "...",
+                                relevance_score=r.relevance_score,
+                                source=r.source,
+                                importance=r.importance,
+                            )
+                            packed_items.append(r_trunc)
+                            total_tokens += pack_tokens
+                break
+
+        content_parts = [r.content for r in packed_items]
+        body = separator.join(content_parts)
+        full_content = header + body
+        total_tokens = header_tokens + self._count_tokens(body)
+
+        return PackResult(
+            content=full_content,
+            total_tokens=total_tokens,
+            budget=budget + header_tokens,
+            items_used=len(packed_items),
+            items_total=len(results),
+        )

memvcs/retrieval/recaller.py

@@ -0,0 +1,105 @@
+"""
+Recall engine - orchestrates strategies and access tracking.
+"""
+
+from typing import List, Optional, Any
+
+from .base import RetrievalStrategy, RecallResult
+from .strategies import RecencyStrategy, ImportanceStrategy, SimilarityStrategy, HybridStrategy
+
+
+class RecallEngine:
+    """Orchestrates recall with pluggable strategies and access tracking."""
+
+    STRATEGIES = ["recency", "importance", "similarity", "hybrid"]
+
+    def __init__(
+        self,
+        repo: Any,
+        vector_store: Optional[Any] = None,
+        access_index: Optional[Any] = None,
+        use_cache: bool = True,
+    ):
+        self.repo = repo
+        self.vector_store = vector_store
+        self.access_index = access_index
+        self.use_cache = use_cache
+
+    def _get_strategy(self, strategy_name: str) -> RetrievalStrategy:
+        """Get strategy instance by name."""
+        name = strategy_name.lower()
+        if name == "recency":
+            return RecencyStrategy(self.repo)
+        if name == "importance":
+            return ImportanceStrategy(self.repo)
+        if name == "similarity":
+            if not self.vector_store:
+                raise ImportError(
+                    "Similarity strategy requires agmem[vector]. Install with: pip install agmem[vector]"
+                )
+            return SimilarityStrategy(self.repo, self.vector_store)
+        if name == "hybrid":
+            return HybridStrategy(self.repo, self.vector_store)
+        raise ValueError(f"Unknown strategy: {strategy_name}. Choose from {self.STRATEGIES}")
+
+    def recall(
+        self,
+        context: str,
+        limit: int = 10,
+        strategy: str = "hybrid",
+        exclude: Optional[List[str]] = None,
+    ) -> List[RecallResult]:
+        """
+        Recall memories for the given context.
+
+        Args:
+            context: Current task description
+            limit: Max results
+            strategy: recency, importance, similarity, or hybrid
+            exclude: Tag/path patterns to exclude
+
+        Returns:
+            Ranked list of RecallResult
+        """
+        exclude_list = [e.strip() for e in (exclude or []) if e.strip()]
+
+        cached = self._get_cached_results(context, strategy, limit, exclude_list)
+        if cached is not None:
+            return cached
+
+        effective_strategy = (
+            "recency" if (strategy == "hybrid" and not self.vector_store) else strategy
+        )
+        strat = self._get_strategy(effective_strategy)
+        results = strat.recall(context=context, limit=limit, exclude=exclude_list)
+
+        self._record_access_and_cache(context, effective_strategy, limit, exclude_list, results)
+        return results
+
+    def _get_cached_results(
+        self, context: str, strategy: str, limit: int, exclude: List[str]
+    ) -> Optional[List[RecallResult]]:
+        if not (self.use_cache and self.access_index and context):
+            return None
+        cached = self.access_index.get_cached_recall(context, strategy, limit, exclude)
+        if not cached or not cached.get("results"):
+            return None
+        return [RecallResult(**r) if isinstance(r, dict) else r for r in cached["results"]]
+
+    def _record_access_and_cache(
+        self,
+        context: str,
+        strategy: str,
+        limit: int,
+        exclude: List[str],
+        results: List[RecallResult],
+    ) -> None:
+        if self.access_index:
+            head = self.repo.get_head_commit()
+            commit_hash = head.store(self.repo.object_store) if head else ""
+            for r in results:
+                self.access_index.record_access(r.path, commit_hash)
+        if self.use_cache and self.access_index and context and results:
+            self.access_index.set_cached_recall(
+                context, strategy, limit, exclude, [r.to_dict() for r in results]
+            )