Release 0.39.1 - Backend-agnostic public API docstrings

Remove ChromaDB, SQLite, MLX, and other implementation-specific
references from public docstrings and API return values. The public
API surface should be backend-agnostic for hosted service users.

Author: hughpyle

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keep
-version: 0.39.0
+version: 0.39.1
 description: Reflective Memory
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim

keep/__init__.py

@@ -7,25 +7,15 @@
 Quick Start:
     from keep import Keeper
 
-    kp = Keeper()  # uses ~/.keep/ by default
+    kp = Keeper()
     kp.update("file:///path/to/document.md", source_tags={"project": "myproject"})
     results = kp.find("something similar to this query")
 
 CLI Usage:
     keep find "query text"
     keep put file:///path/to/doc.md -t category=docs
-    keep collections --json
 
-Default Store:
-    ~/.keep/ in the user's home directory (created automatically).
-    Override with KEEP_STORE_PATH or explicit path argument.
-
-Environment Variables:
-    KEEP_STORE_PATH      - Override default store location
-    KEEP_OPENAI_API_KEY  - API key for OpenAI providers
-
-The store is initialized automatically on first use. Configuration is persisted
-in a TOML file within the store directory.
+The store is initialized automatically on first use.
 """
 
 # Configure quiet mode early (before any library imports)
@@ -47,7 +37,7 @@
 )
 from .types import Item, filter_non_system_tags, SYSTEM_TAG_PREFIX, INTERNAL_TAGS
 
-__version__ = "0.39.0"
+__version__ = "0.39.1"
 __all__ = [
     "Keeper",
     "Item",

keep/api.py

@@ -522,7 +522,7 @@ def _apply_file_size_limit(self, provider: DocumentProvider) -> None:
                     p.max_size = max_size
 
     def _check_store_consistency(self) -> bool:
-        """Check if DocumentStore and ChromaDB ID sets match.
+        """Check if document store and vector store ID sets match.
 
         Returns True if reconciliation is needed. Does not fix —
         that is deferred to the first _upsert call when the
@@ -779,12 +779,8 @@ def _get_embedding_provider(self) -> EmbeddingProvider:
         """
         Get embedding provider, creating it lazily on first use.
 
-        This allows read-only operations to work offline without loading
-        the embedding model (which may try to reach HuggingFace).
-
-        For MLX (local GPU) providers, wraps with a lifecycle lock that
-        serializes model access across processes to prevent GPU memory
-        exhaustion.
+        This allows read-only operations to work without loading
+        the embedding model upfront.
         """
         if self._embedding_provider is None:
             if self._config.embedding is None:
@@ -826,11 +822,7 @@ def _get_embedding_provider(self) -> EmbeddingProvider:
         return self._embedding_provider
 
     def _get_summarization_provider(self) -> SummarizationProvider:
-        """
-        Get summarization provider, creating it lazily on first use.
-
-        For MLX (local GPU) providers, wraps with a lifecycle lock.
-        """
+        """Get summarization provider, creating it lazily on first use."""
         if self._summarization_provider is None:
             registry = get_registry()
             provider = registry.create_summarization(
@@ -851,7 +843,6 @@ def _get_media_describer(self) -> Optional[MediaDescriber]:
         Get media describer, creating it lazily on first use.
 
         Returns None if no media provider is configured or creation fails.
-        For MLX (local GPU) providers, wraps with a lifecycle lock.
         """
         if self._media_describer is None:
             if self._config.media is None:
@@ -949,7 +940,7 @@ def _validate_embedding_identity(self, provider: EmbeddingProvider) -> None:
 
         On first use, records the embedding identity to config.
         On subsequent uses, if the provider changed, silently updates config
-        and triggers background reindex into the new ChromaDB collection.
+        and triggers background reindex into the new vector store collection.
         """
         # Get current provider's identity
         current = EmbeddingIdentity(
@@ -982,7 +973,7 @@ def _validate_embedding_identity(self, provider: EmbeddingProvider) -> None:
                 self._trigger_background_reindex()
 
     def _trigger_background_reindex(self) -> None:
-        """Spawn background thread to populate new ChromaDB collection from DocumentStore."""
+        """Spawn background thread to populate new vector collection from document store."""
         import threading
         chroma_coll = self._resolve_chroma_collection()
         doc_coll = self._resolve_doc_collection()
@@ -1000,7 +991,7 @@ def _background_reindex_safe(self, chroma_coll: str, doc_coll: str) -> None:
             logger.warning("Background reindex failed: %s", e)
 
     def _background_reindex(self, chroma_coll: str, doc_coll: str) -> None:
-        """Populate ChromaDB collection from DocumentStore summaries using batch embedding."""
+        """Populate vector collection from document store summaries using batch embedding."""
         doc_ids = self._document_store.list_ids(doc_coll)
         if not doc_ids:
             return
@@ -1069,7 +1060,7 @@ def reindex(self) -> dict:
         """
         Rebuild search index with current embedding provider (foreground).
 
-        Re-embeds all items from DocumentStore into the current ChromaDB
+        Re-embeds all items from the document store into the current vector
         collection. Use as an explicit backstop when background reindex
         didn't complete.
 
@@ -1142,7 +1133,7 @@ def embedding_identity(self) -> EmbeddingIdentity | None:
         return self._config.embedding_identity
 
     def _resolve_chroma_collection(self) -> str:
-        """ChromaDB collection name derived from embedding identity."""
+        """Vector collection name derived from embedding identity."""
         if self._config.embedding_identity:
             return self._config.embedding_identity.key
         return "default"
@@ -1824,7 +1815,7 @@ def _rank_by_relevance(
         """
         Rank candidate items by similarity to anchor + recency decay.
 
-        Uses stored embeddings from ChromaDB — no re-embedding needed.
+        Uses stored embeddings — no re-embedding needed.
         Falls back to recency-only ranking if embeddings unavailable.
         """
         import math
@@ -2029,7 +2020,7 @@ def get(self, id: str) -> Optional[Item]:
         """
         Retrieve a specific item by ID.
 
-        Reads from document store (canonical), falls back to ChromaDB for legacy data.
+        Reads from document store (canonical), falls back to vector store for legacy data.
         Touches accessed_at on successful retrieval.
         """
         validate_id(id)
@@ -2593,7 +2584,7 @@ def count(self) -> int:
         """
         Count items in a collection.
 
-        Returns count from document store if available, else ChromaDB.
+        Returns count from document store if available, else vector store.
         """
         doc_coll = self._resolve_doc_collection()
         chroma_coll = self._resolve_chroma_collection()
@@ -2814,17 +2805,17 @@ def reconcile(
         fix: bool = False,
     ) -> dict:
         """
-        Check and optionally fix consistency between DocumentStore and ChromaDB.
+        Check and optionally fix consistency between document store and vector store.
 
         Detects:
-        - Documents in DocumentStore missing from ChromaDB (not searchable)
-        - Documents in ChromaDB missing from DocumentStore (orphaned embeddings)
+        - Documents in document store missing from vector store (not searchable)
+        - Documents in vector store missing from document store (orphaned embeddings)
 
         Args:
-            fix: If True, re-index documents missing from ChromaDB
+            fix: If True, re-index documents missing from vector store
 
         Returns:
-            Dict with 'missing_from_chroma', 'orphaned_in_chroma', 'fixed' counts
+            Dict with 'missing_from_index', 'orphaned_in_index', 'fixed' counts
         """
         doc_coll = self._resolve_doc_collection()
         chroma_coll = self._resolve_chroma_collection()
@@ -2868,8 +2859,8 @@ def reconcile(
                     logger.warning("Failed to remove orphan %s: %s", orphan_id, e)
 
         return {
-            "missing_from_chroma": len(missing_from_chroma),
-            "orphaned_in_chroma": len(orphaned_in_chroma),
+            "missing_from_index": len(missing_from_chroma),
+            "orphaned_in_index": len(orphaned_in_chroma),
             "fixed": fixed,
             "removed": removed,
             "missing_ids": list(missing_from_chroma) if missing_from_chroma else [],

keep/backend.py

@@ -2,8 +2,8 @@
 Pluggable storage backend factory.
 
 Creates storage backends (DocumentStore, VectorStore, PendingQueue) based on
-configuration. Local backends use SQLite + ChromaDB. External backends register
-via the ``keep.backends`` entry point group.
+configuration. External backends register via the ``keep.backends`` entry
+point group.
 
 External backend packages provide a factory function::
 
@@ -59,9 +59,7 @@ def create_stores(config: StoreConfig) -> StoreBundle:
     """
     Create storage backends from configuration.
 
-    For ``backend = "local"`` (default), creates SQLite DocumentStore,
-    ChromaDB ChromaStore, and SQLite PendingSummaryQueue.
-
+    For ``backend = "local"`` (default), creates local storage backends.
     For other values, loads the backend via the ``keep.backends`` entry
     point group.
     """

keep/config.py

@@ -135,7 +135,7 @@ class StoreConfig:
     # Remote backend (if set, Keeper delegates to keepnotes.ai API)
     remote: Optional[RemoteConfig] = None
 
-    # Pluggable backend ("local" = default SQLite+ChromaDB, or entry-point name)
+    # Pluggable backend ("local" = default, or entry-point name)
     backend: str = "local"
     backend_params: dict[str, Any] = field(default_factory=dict)
 
@@ -243,13 +243,13 @@ def detect_default_providers() -> dict[str, ProviderConfig | None]:
     Priority for embeddings:
     1. API keys: VOYAGE_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY
     2. Ollama (if running locally with models)
-    3. Local: MLX (Apple Silicon), sentence-transformers
+    3. Local models (if installed)
     4. None if nothing available
 
     Priority for summarization:
     1. API keys: ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN), OPENAI_API_KEY, GEMINI_API_KEY
     2. Ollama (if running locally with a generative model)
-    3. Local: MLX (Apple Silicon)
+    3. Local models (if installed)
     4. Fallback: truncate (always available)
 
     Returns provider configs for: embedding, summarization, document.

keep/data/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "keep",
   "name": "keep",
   "description": "Reflective memory — injects `keep now` context at agent start",
-  "version": "0.39.0",
+  "version": "0.39.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

keep/data/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keep",
-  "version": "0.39.0",
+  "version": "0.39.1",
   "openclaw": {
     "extensions": ["./index.ts"]
   }

keep/protocol.py

@@ -4,7 +4,6 @@
 Defines interface contracts at two levels:
 - KeeperProtocol: the public API (CLI, RemoteKeeper)
 - VectorStoreProtocol / DocumentStoreProtocol: internal storage backends
-  (ChromaDB/SQLite locally, Postgres/pgvector in cloud)
 """
 
 from typing import Any, Optional, Protocol, runtime_checkable
@@ -21,8 +20,8 @@ class KeeperProtocol(Protocol):
     The public interface for reflective memory operations.
 
     Implemented by:
-    - Keeper (local SQLite + ChromaDB backend)
-    - RemoteKeeper (HTTP client to keepnotes.ai API)
+    - Keeper (local backend)
+    - RemoteKeeper (hosted keepnotes.ai API)
     """
 
     # -- Write operations --
@@ -187,9 +186,7 @@ class VectorStoreProtocol(Protocol):
     """
     Abstract vector search backend.
 
-    Implemented by:
-    - ChromaStore (local ChromaDB)
-    - Cloud implementations (pgvector, Qdrant, etc.)
+    Provides embedding storage, similarity search, and metadata queries.
     """
 
     # -- Embedding dimension --
@@ -302,9 +299,7 @@ class DocumentStoreProtocol(Protocol):
     """
     Abstract document metadata backend.
 
-    Implemented by:
-    - DocumentStore (local SQLite)
-    - Cloud implementations (Postgres, etc.)
+    Provides document storage, versioning, and tag-based queries.
     """
 
     # -- Write --
@@ -432,10 +427,7 @@ class PendingQueueProtocol(Protocol):
     """
     Abstract pending summary queue.
 
-    Implemented by:
-    - PendingSummaryQueue (local SQLite)
-    - NullPendingQueue (no-op for backends that handle summarization server-side)
-    - Cloud implementations (Postgres-backed queue, etc.)
+    Manages background summarization of large content.
     """
 
     def enqueue(self, id: str, collection: str, content: str) -> None: ...

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "keep-skill"
-version = "0.39.0"
+version = "0.39.1"
 description = "Reflective memory - remember and search documents by meaning"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"