keep-skill 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

keep/providers/mlx.py

@@ -15,21 +15,18 @@ from .base import EmbeddingProvider, SummarizationProvider, get_registry
 
 class MLXEmbedding:
     """
-    Embedding provider using MLX on Apple Silicon.
-    
-    Uses sentence-transformer compatible models converted to MLX format.
-    
+    Embedding provider using MPS (Metal) acceleration on Apple Silicon.
+
+    Uses sentence-transformer models with GPU acceleration via Metal Performance Shaders.
+
     Requires: pip install mlx sentence-transformers
     """
-    
-    def __init__(self, model: str = "mlx-community/bge-small-en-v1.5"):
+
+    def __init__(self, model: str = "all-MiniLM-L6-v2"):
         """
         Args:
-            model: Model name from mlx-community hub or local path.
-                   Good options:
-                   - mlx-community/bge-small-en-v1.5 (small, fast)
-                   - mlx-community/bge-base-en-v1.5 (balanced)
-                   - mlx-community/bge-large-en-v1.5 (best quality)
+            model: Model name from sentence-transformers hub.
+                   Default: all-MiniLM-L6-v2 (384 dims, fast, no auth required)
         """
         try:
             import mlx.core as mx
@@ -39,17 +36,22 @@ class MLXEmbedding:
                 "MLXEmbedding requires 'mlx' and 'sentence-transformers'. "
                 "Install with: pip install mlx sentence-transformers"
             )
-        
+
         self.model_name = model
-        
-        # sentence-transformers can use MLX backend on Apple Silicon
-        # For MLX-specific models, we use the direct approach
-        if model.startswith("mlx-community/"):
-            # Use sentence-transformers which auto-detects MLX
-            self._model = SentenceTransformer(model, device="mps")
-        else:
-            self._model = SentenceTransformer(model)
-        
+
+        # Check if model is already cached locally to avoid network calls
+        local_only = False
+        try:
+            from huggingface_hub import try_to_load_from_cache
+            repo_id = model if "/" in model else f"sentence-transformers/{model}"
+            cached = try_to_load_from_cache(repo_id, "config.json")
+            local_only = cached is not None
+        except ImportError:
+            pass
+
+        # Use MPS (Metal) for GPU acceleration on Apple Silicon
+        self._model = SentenceTransformer(model, device="mps", local_files_only=local_only)
+
         self._dimension: int | None = None
     
     @property

keep/store.py

@@ -49,13 +49,14 @@ class ChromaStore:
     pluggable backends (SQLite+faiss, Postgres+pgvector, etc.)
     """
     
-    def __init__(self, store_path: Path, embedding_dimension: int):
+    def __init__(self, store_path: Path, embedding_dimension: Optional[int] = None):
         """
         Initialize or open a ChromaDb store.
-        
+
         Args:
             store_path: Directory for persistent storage
-            embedding_dimension: Expected dimension of embeddings (for validation)
+            embedding_dimension: Expected dimension of embeddings (for validation).
+                Can be None for read-only access; will be set on first write.
         """
         try:
             import chromadb
@@ -123,7 +124,7 @@ class ChromaStore:
     ) -> None:
         """
         Insert or update an item in the store.
-        
+
         Args:
             collection: Collection name
             id: Item identifier (URI or custom)
@@ -131,14 +132,17 @@ class ChromaStore:
             summary: Human-readable summary (stored as document)
             tags: All tags (source + system + generated)
         """
-        if len(embedding) != self._embedding_dimension:
+        # Validate or set embedding dimension
+        if self._embedding_dimension is None:
+            self._embedding_dimension = len(embedding)
+        elif len(embedding) != self._embedding_dimension:
             raise ValueError(
                 f"Embedding dimension mismatch: expected {self._embedding_dimension}, "
                 f"got {len(embedding)}"
             )
-        
+
         coll = self._get_collection(collection)
-        
+
         # Add timestamp if not present
         now = datetime.now(timezone.utc).isoformat()
         if "_updated" not in tags:
@@ -154,36 +158,122 @@ class ChromaStore:
                     tags = {**tags, "_created": now}
             else:
                 tags = {**tags, "_created": now}
-        
+
         # Add date portion for easier date queries
         tags = {**tags, "_updated_date": now[:10]}
-        
+
         coll.upsert(
             ids=[id],
             embeddings=[embedding],
             documents=[summary],
             metadatas=[self._tags_to_metadata(tags)],
         )
+
+    def upsert_version(
+        self,
+        collection: str,
+        id: str,
+        version: int,
+        embedding: list[float],
+        summary: str,
+        tags: dict[str, str],
+    ) -> None:
+        """
+        Store an archived version with a versioned ID.
+
+        The versioned ID format is: {id}@v{version}
+        Metadata includes _version and _base_id for filtering/navigation.
+
+        Args:
+            collection: Collection name
+            id: Base item identifier (not versioned)
+            version: Version number (1=oldest archived)
+            embedding: Vector embedding
+            summary: Human-readable summary
+            tags: All tags from the archived version
+        """
+        if self._embedding_dimension is None:
+            self._embedding_dimension = len(embedding)
+        elif len(embedding) != self._embedding_dimension:
+            raise ValueError(
+                f"Embedding dimension mismatch: expected {self._embedding_dimension}, "
+                f"got {len(embedding)}"
+            )
+
+        coll = self._get_collection(collection)
+
+        # Versioned ID format
+        versioned_id = f"{id}@v{version}"
+
+        # Add version metadata
+        versioned_tags = dict(tags)
+        versioned_tags["_version"] = str(version)
+        versioned_tags["_base_id"] = id
+
+        coll.upsert(
+            ids=[versioned_id],
+            embeddings=[embedding],
+            documents=[summary],
+            metadatas=[self._tags_to_metadata(versioned_tags)],
+        )
+
+    def get_content_hash(self, collection: str, id: str) -> Optional[str]:
+        """
+        Get the content hash of an existing item.
+
+        Used to check if content changed (to skip re-embedding).
+
+        Args:
+            collection: Collection name
+            id: Item identifier
+
+        Returns:
+            Content hash if item exists and has one, None otherwise
+        """
+        coll = self._get_collection(collection)
+        result = coll.get(ids=[id], include=["metadatas"])
+
+        if not result["ids"]:
+            return None
+
+        metadata = result["metadatas"][0] or {}
+        return metadata.get("_content_hash")
     
-    def delete(self, collection: str, id: str) -> bool:
+    def delete(self, collection: str, id: str, delete_versions: bool = True) -> bool:
         """
         Delete an item from the store.
-        
+
         Args:
             collection: Collection name
             id: Item identifier
-            
+            delete_versions: If True, also delete versioned copies ({id}@v{N})
+
         Returns:
             True if item existed and was deleted, False if not found
         """
         coll = self._get_collection(collection)
-        
+
         # Check existence first
         existing = coll.get(ids=[id])
         if not existing["ids"]:
             return False
-        
+
         coll.delete(ids=[id])
+
+        if delete_versions:
+            # Delete all versioned copies
+            # Query by _base_id metadata to find all versions
+            try:
+                versions = coll.get(
+                    where={"_base_id": id},
+                    include=[],
+                )
+                if versions["ids"]:
+                    coll.delete(ids=versions["ids"])
+            except Exception:
+                # Metadata filter might fail if no versions exist
+                pass
+
         return True
 
     def update_summary(self, collection: str, id: str, summary: str) -> bool:
@@ -222,6 +312,40 @@ class ChromaStore:
         )
         return True
 
+    def update_tags(self, collection: str, id: str, tags: dict[str, str]) -> bool:
+        """
+        Update tags of an existing item without changing embedding or summary.
+
+        Args:
+            collection: Collection name
+            id: Item identifier
+            tags: New tags dict (replaces existing)
+
+        Returns:
+            True if item was updated, False if not found
+        """
+        coll = self._get_collection(collection)
+
+        # Get existing item
+        existing = coll.get(ids=[id], include=["metadatas"])
+        if not existing["ids"]:
+            return False
+
+        # Update timestamp
+        now = datetime.now(timezone.utc).isoformat()
+        tags = dict(tags)  # Copy to avoid mutating input
+        tags["_updated"] = now
+        tags["_updated_date"] = now[:10]
+
+        # Convert to metadata format
+        metadata = self._tags_to_metadata(tags)
+
+        coll.update(
+            ids=[id],
+            metadatas=[metadata],
+        )
+        return True
+
     # -------------------------------------------------------------------------
     # Read Operations
     # -------------------------------------------------------------------------
@@ -257,7 +381,21 @@ class ChromaStore:
         coll = self._get_collection(collection)
         result = coll.get(ids=[id], include=[])
         return bool(result["ids"])
-    
+
+    def list_ids(self, collection: str) -> list[str]:
+        """
+        List all document IDs in a collection.
+
+        Args:
+            collection: Collection name
+
+        Returns:
+            List of document IDs
+        """
+        coll = self._get_collection(collection)
+        result = coll.get(include=[])
+        return result["ids"]
+
     def query_embedding(
         self,
         collection: str,
@@ -340,27 +478,33 @@ class ChromaStore:
         collection: str,
         query: str,
         limit: int = 10,
+        where: dict[str, Any] | None = None,
     ) -> list[StoreResult]:
         """
         Query by full-text search on document content (summaries).
-        
+
         Args:
             collection: Collection name
             query: Text to search for
             limit: Maximum results to return
-            
+            where: Optional metadata filter (Chroma where clause)
+
         Returns:
             List of matching results
         """
         coll = self._get_collection(collection)
-        
+
         # Chroma's where_document does substring matching
-        result = coll.get(
-            where_document={"$contains": query},
-            limit=limit,
-            include=["documents", "metadatas"],
-        )
-        
+        get_params = {
+            "where_document": {"$contains": query},
+            "limit": limit,
+            "include": ["documents", "metadatas"],
+        }
+        if where:
+            get_params["where"] = where
+
+        result = coll.get(**get_params)
+
         results = []
         for i, id in enumerate(result["ids"]):
             results.append(StoreResult(
@@ -368,7 +512,7 @@ class ChromaStore:
                 summary=result["documents"][i] or "",
                 tags=self._metadata_to_tags(result["metadatas"][i]),
             ))
-        
+
         return results
     
     # -------------------------------------------------------------------------

keep_skill-0.3.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: keep-skill
+Version: 0.3.0
+Summary: Semantic memory - remember and search documents by meaning
+Project-URL: Homepage, https://github.com/hughpyle/keep
+Project-URL: Repository, https://github.com/hughpyle/keep
+Author: Hugh Pyle
+License: MIT
+License-File: LICENSE
+Keywords: agents,chromadb,embeddings,semantic-memory,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Requires-Python: <3.14,>=3.11
+Requires-Dist: chromadb>=0.4
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.9
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: documents
+Requires-Dist: beautifulsoup4>=4.9; extra == 'documents'
+Requires-Dist: pypdf>=5.0; extra == 'documents'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: local
+Requires-Dist: beautifulsoup4>=4.9; extra == 'local'
+Requires-Dist: mlx-lm>=0.10; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'local'
+Requires-Dist: mlx>=0.10; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'local'
+Requires-Dist: pypdf>=5.0; extra == 'local'
+Requires-Dist: sentence-transformers>=2.2; extra == 'local'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.10; extra == 'mlx'
+Requires-Dist: mlx>=0.10; extra == 'mlx'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: openclaw
+Requires-Dist: anthropic>=0.18.0; extra == 'openclaw'
+Requires-Dist: google-genai>=1.0.0; extra == 'openclaw'
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2; extra == 'sentence-transformers'
+Description-Content-Type: text/markdown
+
+# keep
+
+**Semantic memory with version history.**
+
+Index documents and notes. Search by meaning. Track changes over time.
+
+```bash
+pip install 'keep-skill[local]'
+keep init
+
+# Index content
+keep update path/to/document.md -t project=myapp
+keep update "Rate limit is 100 req/min" -t topic=api
+
+# Search by meaning
+keep find "what's the rate limit?"
+
+# Track what you're working on
+keep now "Debugging auth flow"
+keep now -V 1                    # Previous context
+```
+
+---
+
+## What It Does
+
+- **Semantic search** — Find by meaning, not just keywords
+- **Version history** — All documents retain history on update
+- **Tag organization** — Filter and navigate with key=value tags
+- **Recency decay** — Recent items rank higher in search
+- **Works offline** — Local embedding models by default
+
+Backed by ChromaDB for vectors, SQLite for metadata and versions.
+
+---
+
+## Installation
+
+**Python 3.11–3.13 required.**
+
+```bash
+# Recommended: local models (works offline)
+pip install 'keep-skill[local]'
+
+# Or with uv (faster):
+uv tool install 'keep-skill[local]'
+
+# API-based alternative (requires OPENAI_API_KEY)
+pip install 'keep-skill[openai]'
+```
+
+First run downloads embedding models (~3-5 minutes).
+
+---
+
+## Quick Start
+
+```bash
+keep init                              # Creates .keep/ at repo root
+
+# Index files and notes
+keep update file:///path/to/doc.md -t project=myapp
+keep update "Important insight" -t type=note
+
+# Search
+keep find "authentication flow" --limit 5
+keep find "auth" --since P7D           # Last 7 days
+
+# Retrieve
+keep get file:///path/to/doc.md
+keep get ID -V 1                       # Previous version
+keep get ID --history                  # All versions
+
+# Tags
+keep tag project=myapp                 # Find by tag
+keep tag --list                        # List all tags
+
+# Current context
+keep now                               # Show what you're working on
+keep now "Fixing login bug"            # Update context
+```
+
+### Python API
+
+```python
+from keep import Keeper
+
+kp = Keeper()
+
+# Index
+kp.update("file:///path/to/doc.md", tags={"project": "myapp"})
+kp.remember("Rate limit is 100 req/min", tags={"topic": "api"})
+
+# Search
+results = kp.find("rate limit", limit=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.summary}")
+
+# Version history
+prev = kp.get_version("doc:1", offset=1)
+versions = kp.list_versions("doc:1")
+```
+
+See [docs/QUICKSTART.md](docs/QUICKSTART.md) for configuration and more examples.
+
+---
+
+## Documentation
+
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Setup, configuration, lazy summarization
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Complete CLI and API reference
+- **[docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md)** — Working session patterns
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood
+- **[SKILL.md](SKILL.md)** — The reflective practice (for AI agents)
+
+---
+
+## For AI Agents
+
+This library was designed as an agent skill — persistent memory that helps agents reflect before acting and learn from experience.
+
+**The practice:**
+- Pause before acting — `keep find` what you already know
+- Notice breakdowns — when assumptions surface, index them
+- Reflect after — `keep update` learnings for future sessions
+
+See **[SKILL.md](SKILL.md)** for the full practice guide.
+
+---
+
+## Status
+
+**Current:** v0.3.0
+
+**Working:**
+- ✅ Semantic search with embeddings
+- ✅ Document versioning (all updates retain history)
+- ✅ Content-addressed IDs for text (same content = same ID)
+- ✅ Tag queries and full-text search
+- ✅ Current context tracking (`keep now`)
+- ✅ Recency decay (recent items rank higher)
+- ✅ Lazy summarization (background processing)
+- ✅ Provider abstraction (local or API-based)
+
+**Planned** (see [later/](later/)):
+- ⏳ Private/shared routing
+- ⏳ Relationship graphs between items
+- ⏳ LLM-based auto-tagging
+
+---
+
+## License
+
+MIT
+
+---
+
+## Contributing
+
+Published on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).
+
+Issues and PRs welcome:
+- Provider implementations
+- Performance improvements
+- Documentation clarity
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

keep_skill-0.3.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+keep/__init__.py,sha256=ZHguWMkzsurTDqV7_t5Nlr5VHlwVkmG6pelE0Ivfs6I,1581
+keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
+keep/api.py,sha256=rArSGmbQkVR_x5qcMXVZcQr97daWxyettnHplgnykEM,56951
+keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
+keep/cli.py,sha256=yxO9FS0N1c_ffE02NV8tC-4NNj8ZNK_dkFufjqVG84A,34085
+keep/config.py,sha256=RRnHHvhc9KkJBYt0rpAFIvAVXw40b56xtT74TFIBiDU,15832
+keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
+keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
+keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
+keep/indexing.py,sha256=dpPYo3WXnIhFDWinz5ZBZVk7_qumeNpP4EpOIY0zMbs,6063
+keep/logging_config.py,sha256=IGwkgIyg-TfYaT4MnoCXfmjeHAe_wsB_XQ1QhVT_ro8,3503
+keep/paths.py,sha256=Dv7pM6oo2QgjL6sj5wPjhuMOK2wqUkfd4Kz08TwJ1ps,3331
+keep/pending_summaries.py,sha256=_irGe7P1Lmog2c5cEgx-BElpq4YJW-tEmF5A3IUZQbQ,5727
+keep/store.py,sha256=RmKOAWTWvUlMcLoEbyAfR99Cxcshh_2SHhNkKYGAkqw,17509
+keep/types.py,sha256=f6uOSYsYt6mj1ulKn2iRkooi__dWCiOQFPD6he2eID4,2149
+keep/providers/__init__.py,sha256=GFX_12g9OdjmpFUkTekOQBOWvcRW2Ae6yidfVVW2SiI,1095
+keep/providers/base.py,sha256=7Ug4Kj9fK2Dq4zDcZjn-GKsoZBOAlB9b-FMk969ER-g,14590
+keep/providers/documents.py,sha256=EXeSy5i3RUL0kciIC6w3ldAEfbTIyC5fgfzC_WAI0iY,8211
+keep/providers/embedding_cache.py,sha256=gna6PZEJanbn2GUN0vj1b1MC0xVWePM9cot2KgZUdu8,8856
+keep/providers/embeddings.py,sha256=zi8GyitKexdbCJyU1nLrUhGt_zzPn3udYrrPZ5Ak8Wo,9081
+keep/providers/llm.py,sha256=BxROKOklKbkGsHcSADPNNgWQExgSN6Bg4KPQIxVuB3U,12441
+keep/providers/mlx.py,sha256=aNl00r9tGi5tCGj2ArYH7CmDHtL1jLjVzb1rofU1DAo,9050
+keep/providers/summarization.py,sha256=MlVTcYipaqp2lT-QYnznp0AMuPVG36QfcTQnvY7Gb-Q,3409
+keep_skill-0.3.0.dist-info/METADATA,sha256=ET8OzV76N3JI_bWcJt6j6xE0uYmROmgB27U1gq9RAk0,6312
+keep_skill-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+keep_skill-0.3.0.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
+keep_skill-0.3.0.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
+keep_skill-0.3.0.dist-info/RECORD,,