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

keep/__init__.py

@@ -40,7 +40,7 @@ if not os.environ.get("KEEP_VERBOSE"):
 from .api import Keeper, NOWDOC_ID
 from .types import Item, filter_non_system_tags, SYSTEM_TAG_PREFIX
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 __all__ = [
     "Keeper",
     "Item",

keep/api.py

@@ -902,7 +902,88 @@ class Keeper:
             items = _filter_by_date(items, since)
 
         return items[:limit]
-    
+
+    def get_similar_for_display(
+        self,
+        id: str,
+        *,
+        limit: int = 3,
+        collection: Optional[str] = None
+    ) -> list[Item]:
+        """
+        Find similar items for frontmatter display using stored embedding.
+
+        Optimized for display: uses stored embedding (no re-embedding),
+        filters to distinct base documents, excludes source document versions.
+
+        Args:
+            id: ID of item to find similar items for
+            limit: Maximum results to return
+            collection: Target collection
+
+        Returns:
+            List of similar items, one per unique base document
+        """
+        coll = self._resolve_collection(collection)
+
+        # Get the stored embedding (no re-embedding)
+        embedding = self._store.get_embedding(coll, id)
+        if embedding is None:
+            return []
+
+        # Fetch more than needed to account for version filtering
+        fetch_limit = limit * 3
+        results = self._store.query_embedding(coll, embedding, limit=fetch_limit)
+
+        # Convert to Items
+        items = [r.to_item() for r in results]
+
+        # Extract base ID of source document
+        source_base_id = id.split("@v")[0] if "@v" in id else id
+
+        # Filter to distinct base IDs, excluding source document
+        seen_base_ids: set[str] = set()
+        filtered: list[Item] = []
+        for item in items:
+            # Get base ID from tags or parse from ID
+            base_id = item.tags.get("_base_id", item.id.split("@v")[0] if "@v" in item.id else item.id)
+
+            # Skip versions of source document
+            if base_id == source_base_id:
+                continue
+
+            # Keep only first version of each document
+            if base_id not in seen_base_ids:
+                seen_base_ids.add(base_id)
+                filtered.append(item)
+
+                if len(filtered) >= limit:
+                    break
+
+        return filtered
+
+    def get_version_offset(self, item: Item, collection: Optional[str] = None) -> int:
+        """
+        Get version offset (0=current, 1=previous, ...) for an item.
+
+        Converts the internal version number (1=oldest, 2=next...) to the
+        user-visible offset format (0=current, 1=previous, 2=two-ago...).
+
+        Args:
+            item: Item to get version offset for
+            collection: Target collection
+
+        Returns:
+            Version offset (0 for current version)
+        """
+        version_tag = item.tags.get("_version")
+        if not version_tag:
+            return 0  # Current version
+        base_id = item.tags.get("_base_id", item.id)
+        coll = self._resolve_collection(collection)
+        version_count = self._document_store.version_count(coll, base_id)
+        return version_count - int(version_tag) + 1
+
     def query_fulltext(
         self,
         query: str,

keep/cli.py

@@ -9,6 +9,7 @@ Usage:
 
 import json
 import os
+import re
 import sys
 from pathlib import Path
 from typing import Optional
@@ -16,6 +17,9 @@ from typing import Optional
 import typer
 from typing_extensions import Annotated
 
+# Pattern for version identifier suffix: @V{N} where N is digits only
+VERSION_SUFFIX_PATTERN = re.compile(r'@V\{(\d+)\}$')
+
 from .api import Keeper, _text_content_id
 from .document_store import VersionInfo
 from .types import Item
@@ -38,6 +42,7 @@ def _verbose_callback(value: bool):
 # Global state for CLI options
 _json_output = False
 _ids_output = False
+_full_output = False
 
 
 def _json_callback(value: bool):
@@ -58,18 +63,30 @@ def _get_ids_output() -> bool:
     return _ids_output
 
 
+def _full_callback(value: bool):
+    global _full_output
+    _full_output = value
+
+
+def _get_full_output() -> bool:
+    return _full_output
+
+
 app = typer.Typer(
     name="keep",
     help="Associative memory with semantic search.",
     no_args_is_help=False,
     invoke_without_command=True,
+    rich_markup_mode=None,
 )
 
 
 def _format_yaml_frontmatter(
     item: Item,
     version_nav: Optional[dict[str, list[VersionInfo]]] = None,
-    viewing_version: Optional[int] = None,
+    viewing_offset: Optional[int] = None,
+    similar_items: Optional[list[Item]] = None,
+    similar_offsets: Optional[dict[str, int]] = None,
 ) -> str:
     """
     Format item as YAML frontmatter with summary as content.
@@ -77,41 +94,63 @@ def _format_yaml_frontmatter(
     Args:
         item: The item to format
         version_nav: Optional version navigation info (prev/next lists)
-        viewing_version: If viewing an old version, the version number
+        viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
+        similar_items: Optional list of similar items to display
+        similar_offsets: Version offsets for similar items (item.id -> offset)
+
+    Note: Offset computation (v1, v2, etc.) assumes version_nav lists
+    are ordered newest-first, matching list_versions() ordering.
+    Changing that ordering would break the vN = -V N correspondence.
     """
     lines = ["---", f"id: {item.id}"]
-    if viewing_version is not None:
-        lines.append(f"version: {viewing_version}")
+    if viewing_offset is not None:
+        lines.append(f"version: {viewing_offset}")
     if item.tags:
-        lines.append("tags:")
-        for k, v in sorted(item.tags.items()):
-            lines.append(f"  {k}: {v}")
+        tag_items = ", ".join(f"{k}: {v}" for k, v in sorted(item.tags.items()))
+        lines.append(f"tags: {{{tag_items}}}")
     if item.score is not None:
         lines.append(f"score: {item.score:.3f}")
 
-    # Add version navigation if available
+    # Add similar items if available (version-scoped IDs with date and summary)
+    if similar_items:
+        lines.append("similar:")
+        for sim_item in similar_items:
+            base_id = sim_item.tags.get("_base_id", sim_item.id)
+            offset = (similar_offsets or {}).get(sim_item.id, 0)
+            score_str = f"({sim_item.score:.2f})" if sim_item.score else ""
+            date_part = sim_item.tags.get("_updated", sim_item.tags.get("_created", ""))[:10]
+            summary_preview = sim_item.summary[:40].replace("\n", " ")
+            if len(sim_item.summary) > 40:
+                summary_preview += "..."
+            lines.append(f"  - {base_id}@V{{{offset}}} {score_str} {date_part} {summary_preview}")
+
+    # Add version navigation (just @V{N} since ID is shown at top, with date + summary)
     if version_nav:
+        # Current offset (0 if viewing current)
+        current_offset = viewing_offset if viewing_offset is not None else 0
+
         if version_nav.get("prev"):
             lines.append("prev:")
-            for v in version_nav["prev"]:
-                # Show version number, date portion, and truncated summary
-                date_part = v.created_at[:10] if v.created_at else "unknown"
+            for i, v in enumerate(version_nav["prev"]):
+                prev_offset = current_offset + i + 1
+                date_part = v.created_at[:10] if v.created_at else ""
                 summary_preview = v.summary[:40].replace("\n", " ")
                 if len(v.summary) > 40:
                     summary_preview += "..."
-                lines.append(f"  - {v.version}: {date_part} {summary_preview}")
+                lines.append(f"  - @V{{{prev_offset}}} {date_part} {summary_preview}")
         if version_nav.get("next"):
             lines.append("next:")
-            for v in version_nav["next"]:
-                date_part = v.created_at[:10] if v.created_at else "unknown"
+            for i, v in enumerate(version_nav["next"]):
+                next_offset = current_offset - i - 1
+                date_part = v.created_at[:10] if v.created_at else ""
                 summary_preview = v.summary[:40].replace("\n", " ")
                 if len(v.summary) > 40:
                     summary_preview += "..."
-                lines.append(f"  - {v.version}: {date_part} {summary_preview}")
-        elif viewing_version is not None:
+                lines.append(f"  - @V{{{next_offset}}} {date_part} {summary_preview}")
+        elif viewing_offset is not None:
             # Viewing old version and next is empty means current is next
             lines.append("next:")
-            lines.append("  - current")
+            lines.append(f"  - @V{{0}}")
 
     lines.append("---")
     lines.append(item.summary)  # Summary IS the content
@@ -139,15 +178,29 @@ def main_callback(
         callback=_ids_callback,
         is_eager=True,
     )] = False,
+    full_output: Annotated[bool, typer.Option(
+        "--full", "-F",
+        help="Output full items (overrides --ids)",
+        callback=_full_callback,
+        is_eager=True,
+    )] = False,
 ):
     """Associative memory with semantic search."""
     # If no subcommand provided, show the current context (now)
     if ctx.invoked_subcommand is None:
+        from .api import NOWDOC_ID
         kp = _get_keeper(None, "default")
         item = kp.get_now()
-        typer.echo(_format_item(item, as_json=_get_json_output()))
-        if not _get_json_output():
-            typer.echo("\nUse --help for commands.", err=True)
+        version_nav = kp.get_version_nav(NOWDOC_ID, None, collection="default")
+        similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection="default")
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            similar_items=similar_items,
+            similar_offsets=similar_offsets,
+        ))
 
 
 # -----------------------------------------------------------------------------
@@ -197,13 +250,23 @@ def _format_item(
     item: Item,
     as_json: bool = False,
     version_nav: Optional[dict[str, list[VersionInfo]]] = None,
-    viewing_version: Optional[int] = None,
+    viewing_offset: Optional[int] = None,
+    similar_items: Optional[list[Item]] = None,
+    similar_offsets: Optional[dict[str, int]] = None,
 ) -> str:
     """
     Format an item for display.
 
     Text format: YAML frontmatter (matches docs/system format)
     With --ids: just the ID (for piping)
+
+    Args:
+        item: The item to format
+        as_json: Output as JSON
+        version_nav: Optional version navigation info (prev/next lists)
+        viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
+        similar_items: Optional list of similar items to display
+        similar_offsets: Version offsets for similar items (item.id -> offset)
     """
     if _get_ids_output():
         return json.dumps(item.id) if as_json else item.id
@@ -215,17 +278,47 @@ def _format_item(
             "tags": item.tags,
             "score": item.score,
         }
-        if viewing_version is not None:
-            result["version"] = viewing_version
+        if viewing_offset is not None:
+            result["version"] = viewing_offset
+            result["vid"] = f"{item.id}@V{{{viewing_offset}}}"
+        if similar_items:
+            result["similar"] = [
+                {
+                    "id": f"{s.tags.get('_base_id', s.id)}@V{{{(similar_offsets or {}).get(s.id, 0)}}}",
+                    "score": s.score,
+                    "date": s.tags.get("_updated", s.tags.get("_created", ""))[:10],
+                    "summary": s.summary[:60],
+                }
+                for s in similar_items
+            ]
         if version_nav:
-            result["version_nav"] = {
-                k: [{"version": v.version, "created_at": v.created_at, "summary": v.summary[:60]}
-                    for v in versions]
-                for k, versions in version_nav.items()
-            }
+            current_offset = viewing_offset if viewing_offset is not None else 0
+            result["version_nav"] = {}
+            if version_nav.get("prev"):
+                result["version_nav"]["prev"] = [
+                    {
+                        "offset": current_offset + i + 1,
+                        "vid": f"{item.id}@V{{{current_offset + i + 1}}}",
+                        "created_at": v.created_at,
+                        "summary": v.summary[:60],
+                    }
+                    for i, v in enumerate(version_nav["prev"])
+                ]
+            if version_nav.get("next"):
+                result["version_nav"]["next"] = [
+                    {
+                        "offset": current_offset - i - 1,
+                        "vid": f"{item.id}@V{{{current_offset - i - 1}}}",
+                        "created_at": v.created_at,
+                        "summary": v.summary[:60],
+                    }
+                    for i, v in enumerate(version_nav["next"])
+                ]
+            elif viewing_offset is not None:
+                result["version_nav"]["next"] = [{"offset": 0, "vid": f"{item.id}@V{{0}}", "label": "current"}]
         return json.dumps(result)
 
-    return _format_yaml_frontmatter(item, version_nav, viewing_version)
+    return _format_yaml_frontmatter(item, version_nav, viewing_offset, similar_items, similar_offsets)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
@@ -338,7 +431,7 @@ def find(
 
 @app.command()
 def search(
-    query: Annotated[str, typer.Argument(help="Full-text search query")],
+    query: Annotated[str, typer.Argument(default=..., help="Full-text search query")],
     store: StoreOption = None,
     collection: CollectionOption = "default",
     limit: LimitOption = 10,
@@ -364,11 +457,22 @@ def list_recent(
     """
     List recent items by update time.
 
-    Shows the most recently updated items, newest first.
+    Shows IDs by default (composable). Use --full for detailed output.
     """
     kp = _get_keeper(store, collection)
     results = kp.list_recent(limit=limit)
-    typer.echo(_format_items(results, as_json=_get_json_output()))
+
+    # Determine output mode: --full > --ids > command default (IDs for list)
+    if _get_json_output():
+        # JSON always outputs full items
+        typer.echo(_format_items(results, as_json=True))
+    elif _get_full_output():
+        # --full flag: full YAML output
+        typer.echo(_format_items(results, as_json=False))
+    else:
+        # Default for list: IDs only (composable)
+        for item in results:
+            typer.echo(item.id)
 
 
 @app.command()
@@ -429,7 +533,7 @@ def tag(
 
 @app.command("tag-update")
 def tag_update(
-    ids: Annotated[list[str], typer.Argument(help="Document IDs to tag")],
+    ids: Annotated[list[str], typer.Argument(default=..., help="Document IDs to tag")],
     tags: Annotated[Optional[list[str]], typer.Option(
         "--tag", "-t",
         help="Tag as key=value (empty value removes: key=)"
@@ -605,34 +709,46 @@ def now(
         versions = kp.list_versions(NOWDOC_ID, limit=50, collection=collection)
         current = kp.get(NOWDOC_ID, collection=collection)
 
-        if _get_json_output():
+        if _get_ids_output():
+            # Output version identifiers, one per line
+            if current:
+                typer.echo(f"{NOWDOC_ID}@V{{0}}")
+            for i in range(1, len(versions) + 1):
+                typer.echo(f"{NOWDOC_ID}@V{{{i}}}")
+        elif _get_json_output():
             result = {
                 "id": NOWDOC_ID,
                 "current": {
                     "summary": current.summary if current else None,
+                    "offset": 0,
+                    "vid": f"{NOWDOC_ID}@V{{0}}",
                 } if current else None,
                 "versions": [
                     {
+                        "offset": i + 1,
+                        "vid": f"{NOWDOC_ID}@V{{{i + 1}}}",
                         "version": v.version,
                         "summary": v.summary[:60],
                         "created_at": v.created_at,
                     }
-                    for v in versions
+                    for i, v in enumerate(versions)
                 ],
             }
             typer.echo(json.dumps(result, indent=2))
         else:
             if current:
                 summary_preview = current.summary[:60].replace("\n", " ")
-                typer.echo(f"Current: {summary_preview}...")
+                if len(current.summary) > 60:
+                    summary_preview += "..."
+                typer.echo(f"v0 (current): {summary_preview}")
             if versions:
-                typer.echo(f"\nVersion history ({len(versions)} archived):")
-                for v in versions:
+                typer.echo(f"\nArchived:")
+                for i, v in enumerate(versions, start=1):
                     date_part = v.created_at[:10] if v.created_at else "unknown"
                     summary_preview = v.summary[:50].replace("\n", " ")
                     if len(v.summary) > 50:
                         summary_preview += "..."
-                    typer.echo(f"  v{v.version} ({date_part}): {summary_preview}")
+                    typer.echo(f"  v{i} ({date_part}): {summary_preview}")
             else:
                 typer.echo("No version history.")
         return
@@ -642,25 +758,26 @@ def now(
         offset = version
         if offset == 0:
             item = kp.get_now()
-            viewing_version = None
+            internal_version = None
         else:
             item = kp.get_version(NOWDOC_ID, offset, collection=collection)
+            # Get internal version number for API call
             versions = kp.list_versions(NOWDOC_ID, limit=1, collection=collection)
             if versions:
-                viewing_version = versions[0].version - (offset - 1)
+                internal_version = versions[0].version - (offset - 1)
             else:
-                viewing_version = None
+                internal_version = None
 
         if item is None:
             typer.echo(f"Version not found (offset {offset})", err=True)
             raise typer.Exit(1)
 
-        version_nav = kp.get_version_nav(NOWDOC_ID, viewing_version, collection=collection)
+        version_nav = kp.get_version_nav(NOWDOC_ID, internal_version, collection=collection)
         typer.echo(_format_item(
             item,
             as_json=_get_json_output(),
             version_nav=version_nav,
-            viewing_version=viewing_version,
+            viewing_offset=offset if offset > 0 else None,
         ))
         return
 
@@ -700,19 +817,23 @@ def now(
         item = kp.set_now(new_content, tags=parsed_tags or None)
         typer.echo(_format_item(item, as_json=_get_json_output()))
     else:
-        # Get current context with version navigation
+        # Get current context with version navigation and similar items
         item = kp.get_now()
         version_nav = kp.get_version_nav(NOWDOC_ID, None, collection=collection)
+        similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
         typer.echo(_format_item(
             item,
             as_json=_get_json_output(),
             version_nav=version_nav,
+            similar_items=similar_items,
+            similar_offsets=similar_offsets,
         ))
 
 
 @app.command()
 def get(
-    id: Annotated[str, typer.Argument(help="URI of item to retrieve")],
+    id: Annotated[str, typer.Argument(default=..., help="URI of item (append @V{N} for version)")],
     version: Annotated[Optional[int], typer.Option(
         "--version", "-V",
         help="Get specific version (0=current, 1=previous, etc.)"
@@ -721,108 +842,187 @@ def get(
         "--history", "-H",
         help="List all versions"
     )] = False,
+    similar: Annotated[bool, typer.Option(
+        "--similar", "-S",
+        help="List similar items"
+    )] = False,
+    no_similar: Annotated[bool, typer.Option(
+        "--no-similar",
+        help="Suppress similar items in output"
+    )] = False,
+    limit: Annotated[int, typer.Option(
+        "--limit", "-n",
+        help="Max items for --history or --similar (default: 10)"
+    )] = 10,
     store: StoreOption = None,
     collection: CollectionOption = "default",
 ):
     """
     Retrieve a specific item by ID.
 
+    Version identifiers: Append @V{N} to get a specific version.
+
     Examples:
-        keep get doc:1                  # Current version with prev nav
+        keep get doc:1                  # Current version with similar items
         keep get doc:1 -V 1             # Previous version with prev/next nav
+        keep get "doc:1@V{1}"           # Same as -V 1
         keep get doc:1 --history        # List all versions
+        keep get doc:1 --similar        # List similar items
+        keep get doc:1 --no-similar     # Suppress similar items
     """
     kp = _get_keeper(store, collection)
 
+    # Parse @V{N} version identifier from ID (security: check literal first)
+    actual_id = id
+    version_from_id = None
+
+    if kp.exists(id, collection=collection):
+        # Literal ID exists - use it directly (prevents confusion attacks)
+        actual_id = id
+    else:
+        # Try parsing @V{N} suffix
+        match = VERSION_SUFFIX_PATTERN.search(id)
+        if match:
+            version_from_id = int(match.group(1))
+            actual_id = id[:match.start()]
+
+    # Version from ID only applies if --version not explicitly provided
+    if version is None and version_from_id is not None:
+        version = version_from_id
+
     if history:
         # List all versions
-        versions = kp.list_versions(id, limit=50, collection=collection)
-        current = kp.get(id, collection=collection)
+        versions = kp.list_versions(actual_id, limit=limit, collection=collection)
+        current = kp.get(actual_id, collection=collection)
 
-        if _get_json_output():
+        if _get_ids_output():
+            # Output version identifiers, one per line
+            if current:
+                typer.echo(f"{actual_id}@V{{0}}")
+            for i in range(1, len(versions) + 1):
+                typer.echo(f"{actual_id}@V{{{i}}}")
+        elif _get_json_output():
             result = {
-                "id": id,
+                "id": actual_id,
                 "current": {
                     "summary": current.summary if current else None,
                     "tags": current.tags if current else {},
+                    "offset": 0,
+                    "vid": f"{actual_id}@V{{0}}",
                 } if current else None,
                 "versions": [
                     {
+                        "offset": i + 1,
+                        "vid": f"{actual_id}@V{{{i + 1}}}",
                         "version": v.version,
                         "summary": v.summary,
                         "created_at": v.created_at,
                     }
-                    for v in versions
+                    for i, v in enumerate(versions)
                 ],
             }
             typer.echo(json.dumps(result, indent=2))
         else:
             if current:
-                typer.echo(f"Current: {current.summary[:60]}...")
+                summary_preview = current.summary[:60].replace("\n", " ")
+                if len(current.summary) > 60:
+                    summary_preview += "..."
+                typer.echo(f"v0 (current): {summary_preview}")
             if versions:
-                typer.echo(f"\nVersion history ({len(versions)} archived):")
-                for v in versions:
+                typer.echo(f"\nArchived:")
+                for i, v in enumerate(versions, start=1):
                     date_part = v.created_at[:10] if v.created_at else "unknown"
                     summary_preview = v.summary[:50].replace("\n", " ")
                     if len(v.summary) > 50:
                         summary_preview += "..."
-                    typer.echo(f"  v{v.version} ({date_part}): {summary_preview}")
+                    typer.echo(f"  v{i} ({date_part}): {summary_preview}")
             else:
                 typer.echo("No version history.")
         return
 
+    if similar:
+        # List similar items
+        similar_items = kp.get_similar_for_display(actual_id, limit=limit, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
+
+        if _get_ids_output():
+            # Output version-scoped IDs one per line
+            for item in similar_items:
+                base_id = item.tags.get("_base_id", item.id)
+                offset = similar_offsets.get(item.id, 0)
+                typer.echo(f"{base_id}@V{{{offset}}}")
+        elif _get_json_output():
+            result = {
+                "id": actual_id,
+                "similar": [
+                    {
+                        "id": f"{item.tags.get('_base_id', item.id)}@V{{{similar_offsets.get(item.id, 0)}}}",
+                        "score": item.score,
+                        "date": item.tags.get("_updated", item.tags.get("_created", ""))[:10],
+                        "summary": item.summary[:60],
+                    }
+                    for item in similar_items
+                ],
+            }
+            typer.echo(json.dumps(result, indent=2))
+        else:
+            typer.echo(f"Similar to {actual_id}:")
+            if similar_items:
+                for item in similar_items:
+                    base_id = item.tags.get("_base_id", item.id)
+                    offset = similar_offsets.get(item.id, 0)
+                    score_str = f"({item.score:.2f})" if item.score else ""
+                    date_part = item.tags.get("_updated", item.tags.get("_created", ""))[:10]
+                    summary_preview = item.summary[:50].replace("\n", " ")
+                    if len(item.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  {base_id}@V{{{offset}}} {score_str} {date_part} {summary_preview}")
+            else:
+                typer.echo("  No similar items found.")
+        return
+
     # Get specific version or current
     offset = version if version is not None else 0
 
     if offset == 0:
-        item = kp.get(id, collection=collection)
-        viewing_version = None
+        item = kp.get(actual_id, collection=collection)
+        internal_version = None
     else:
-        item = kp.get_version(id, offset, collection=collection)
-        # Calculate actual version number for display
-        versions = kp.list_versions(id, limit=1, collection=collection)
+        item = kp.get_version(actual_id, offset, collection=collection)
+        # Calculate internal version number for API call
+        versions = kp.list_versions(actual_id, limit=1, collection=collection)
         if versions:
-            viewing_version = versions[0].version - (offset - 1)
+            internal_version = versions[0].version - (offset - 1)
         else:
-            viewing_version = None
+            internal_version = None
 
     if item is None:
         if offset > 0:
-            typer.echo(f"Version not found: {id} (offset {offset})", err=True)
+            typer.echo(f"Version not found: {actual_id} (offset {offset})", err=True)
         else:
-            typer.echo(f"Not found: {id}", err=True)
+            typer.echo(f"Not found: {actual_id}", err=True)
         raise typer.Exit(1)
 
     # Get version navigation
-    version_nav = kp.get_version_nav(id, viewing_version, collection=collection)
+    version_nav = kp.get_version_nav(actual_id, internal_version, collection=collection)
+
+    # Get similar items (unless suppressed or viewing old version)
+    similar_items = None
+    similar_offsets = None
+    if not no_similar and offset == 0:
+        similar_items = kp.get_similar_for_display(actual_id, limit=3, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
 
     typer.echo(_format_item(
         item,
         as_json=_get_json_output(),
         version_nav=version_nav,
-        viewing_version=viewing_version,
+        viewing_offset=offset if offset > 0 else None,
+        similar_items=similar_items,
+        similar_offsets=similar_offsets,
     ))
 
 
-@app.command()
-def exists(
-    id: Annotated[str, typer.Argument(help="URI to check")],
-    store: StoreOption = None,
-    collection: CollectionOption = "default",
-):
-    """
-    Check if an item exists in the store.
-    """
-    kp = _get_keeper(store, collection)
-    found = kp.exists(id)
-    
-    if found:
-        typer.echo(f"Exists: {id}")
-    else:
-        typer.echo(f"Not found: {id}")
-        raise typer.Exit(1)
-
-
 @app.command("collections")
 def list_collections(
     store: StoreOption = None,
@@ -910,45 +1110,6 @@ def config(
             typer.echo(f"  Summarization: {cfg.summarization.name}")
 
 
-@app.command("system")
-def list_system(
-    store: StoreOption = None,
-):
-    """
-    List the system documents.
-
-    Shows ID and summary for each. Use `keep get ID` for full details.
-    """
-    kp = _get_keeper(store, "default")
-    docs = kp.list_system_documents()
-
-    # Use --ids flag for pipe-friendly output
-    if _get_ids_output():
-        ids = [doc.id for doc in docs]
-        if _get_json_output():
-            typer.echo(json.dumps(ids))
-        else:
-            for doc_id in ids:
-                typer.echo(doc_id)
-        return
-
-    if _get_json_output():
-        typer.echo(json.dumps([
-            {"id": doc.id, "summary": doc.summary}
-            for doc in docs
-        ], indent=2))
-    else:
-        if not docs:
-            typer.echo("No system documents.")
-        else:
-            for doc in docs:
-                # Compact summary: collapse whitespace, truncate to 70 chars
-                summary = " ".join(doc.summary.split())[:70]
-                if len(doc.summary) > 70:
-                    summary += "..."
-                typer.echo(f"{doc.id}: {summary}")
-
-
 @app.command("process-pending")
 def process_pending(
     store: StoreOption = None,

keep/config.py

@@ -14,10 +14,7 @@ from pathlib import Path
 from typing import Any, Optional
 
 # tomli_w for writing TOML (tomllib is read-only)
-try:
-    import tomli_w
-except ImportError:
-    tomli_w = None  # type: ignore
+import tomli_w
 
 
 CONFIG_FILENAME = "keep.toml"
@@ -387,9 +384,6 @@ def save_config(config: StoreConfig) -> None:
 
     Creates the directory if it doesn't exist.
     """
-    if tomli_w is None:
-        raise RuntimeError("tomli_w is required to save config. Install with: pip install tomli-w")
-
     # Ensure config directory exists
     config_location = config.config_dir if config.config_dir else config.path
     config_location.mkdir(parents=True, exist_ok=True)

keep/store.py

@@ -58,15 +58,9 @@ class ChromaStore:
             embedding_dimension: Expected dimension of embeddings (for validation).
                 Can be None for read-only access; will be set on first write.
         """
-        try:
-            import chromadb
-            from chromadb.config import Settings
-        except ImportError:
-            raise RuntimeError(
-                "ChromaStore requires 'chromadb' library. "
-                "Install with: pip install chromadb"
-            )
-        
+        import chromadb
+        from chromadb.config import Settings
+
         self._store_path = store_path
         self._embedding_dimension = embedding_dimension
         
@@ -382,6 +376,23 @@ class ChromaStore:
         result = coll.get(ids=[id], include=[])
         return bool(result["ids"])
 
+    def get_embedding(self, collection: str, id: str) -> list[float] | None:
+        """
+        Retrieve the stored embedding for a document.
+
+        Args:
+            collection: Collection name
+            id: Item identifier
+
+        Returns:
+            Embedding vector if found, None otherwise
+        """
+        coll = self._get_collection(collection)
+        result = coll.get(ids=[id], include=["embeddings"])
+        if not result["ids"] or result["embeddings"] is None or len(result["embeddings"]) == 0:
+            return None
+        return list(result["embeddings"][0])
+
     def list_ids(self, collection: str) -> list[str]:
         """
         List all document IDs in a collection.

{keep_skill-0.3.0.dist-info → keep_skill-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.3.0
+Version: 0.4.2
 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
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
 Index documents and notes. Search by meaning. Track changes over time.
 
 ```bash
-pip install 'keep-skill[local]'
+uv tool install 'keep-skill[local]'
 keep init
 
 # Index content
@@ -90,16 +90,20 @@ Backed by ChromaDB for vectors, SQLite for metadata and versions.
 **Python 3.11–3.13 required.**
 
 ```bash
-# Recommended: local models (works offline)
-pip install 'keep-skill[local]'
-
-# Or with uv (faster):
+# Recommended: uv (isolated environment, fast)
 uv tool install 'keep-skill[local]'
 
-# API-based alternative (requires OPENAI_API_KEY)
-pip install 'keep-skill[openai]'
+# Alternative: pip in a virtual environment
+python -m venv .venv && source .venv/bin/activate
+pip install 'keep-skill[local]'
+
+# API-based (requires OPENAI_API_KEY)
+uv tool install 'keep-skill[openai]'
 ```
 
+> **Note:** Always use an isolated environment (uv or venv). Installing with system pip
+> may cause version conflicts with dependencies like typer.
+
 First run downloads embedding models (~3-5 minutes).
 
 ---
@@ -120,6 +124,7 @@ 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@V{1}"                     # Same as -V 1 (version identifier)
 keep get ID --history                  # All versions
 
 # Tags

{keep_skill-0.3.0.dist-info → keep_skill-0.4.2.dist-info}/RECORD

@@ -1,9 +1,9 @@
-keep/__init__.py,sha256=ZHguWMkzsurTDqV7_t5Nlr5VHlwVkmG6pelE0Ivfs6I,1581
+keep/__init__.py,sha256=1WVkySoomQuf9-o3pIKs1CC2OwIyfkiaCxn-mO6nhd8,1581
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=rArSGmbQkVR_x5qcMXVZcQr97daWxyettnHplgnykEM,56951
+keep/api.py,sha256=7oa6jdmeE55dATOEVw18sXGVBVndjiD_7tMDcP_xl_0,59746
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=yxO9FS0N1c_ffE02NV8tC-4NNj8ZNK_dkFufjqVG84A,34085
-keep/config.py,sha256=RRnHHvhc9KkJBYt0rpAFIvAVXw40b56xtT74TFIBiDU,15832
+keep/cli.py,sha256=DzZ5Dy4U25q-Mnbv5WbfRsZaN-ped24GDk34fVddmFA,42440
+keep/config.py,sha256=xhsTS_55HSzYxFNGt2z0q_0Ne-s9L9_3om8Uf_8gHB4,15643
 keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
 keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
 keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
@@ -11,7 +11,7 @@ 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/store.py,sha256=SBc2QdTyApdDDVjm2uZQI6tGbV5Hurfetgj7dyTO65o,17881
 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
@@ -21,8 +21,8 @@ keep/providers/embeddings.py,sha256=zi8GyitKexdbCJyU1nLrUhGt_zzPn3udYrrPZ5Ak8Wo,
 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,,
+keep_skill-0.4.2.dist-info/METADATA,sha256=GKkPrekD30dauxLoogAmSaoD2zhIxltJ4RDkg7yPvzk,6606
+keep_skill-0.4.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+keep_skill-0.4.2.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
+keep_skill-0.4.2.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
+keep_skill-0.4.2.dist-info/RECORD,,