keep-skill 0.3.0__tar.gz → 0.4.1__tar.gz

{keep_skill-0.3.0 → keep_skill-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.3.0
+Version: 0.4.1
 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
@@ -120,6 +120,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 → keep_skill-0.4.1}/README.md

@@ -69,6 +69,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 → keep_skill-0.4.1}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keep
-version: 0.3.0
+version: 0.4.1
 description: Associative memory for reflection and skillful action
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim
@@ -26,12 +26,16 @@ You have a memory. Use it — not sometimes, but as practice.
 
 Ground yourself:
 1. What kind of conversation is this? (Action? Possibility? Clarification?)
-2. What do I already know about this?
+2. Where am I? What's the current context?
+   ```bash
+   keep now
+   ```
+3. What do I already know about this?
    ```bash
    keep find "what I'm about to work on"
    ```
-3. Be here, now, "aquí donde los papas queman", and reflect.
-4. Only then: act.  
+4. Be here, now, "aquí donde los papas queman", and reflect.
+5. Only then: act.  
 
 **After acting, reflect:**
 - What happened? What did I learn?
@@ -166,13 +170,25 @@ keep now --history     # All versions
 
 This helps future you (and other agents) pick up where you left off.
 
+### Similar Items for Discovery
+
+When you retrieve an item, you automatically see related items:
+
+```bash
+keep get ID                  # Shows up to 3 similar items
+keep get ID --similar        # List more similar items
+keep get ID --no-similar     # Just the document
+```
+
+This enables serendipitous discovery — you may find relevant context you didn't know to search for.
+
 ### Version History
 
 All documents retain history on update. Use this to see how understanding evolved:
 
 ```bash
 keep get ID -V 1       # Previous version
-keep get ID --history  # All versions
+keep get ID --history  # List all versions (default 10, -n to override)
 ```
 
 Text updates use content-addressed IDs — same content = same ID. This enables versioning through tag changes:
@@ -244,14 +260,13 @@ Don't dump everything into context. Navigate the tree:
 | `find` | Semantic similarity search | `keep find "authentication flow" --limit 5` |
 | `find --id` | Find similar to existing item | `keep find --id "docid" --limit 3` |
 | `search` | Full-text search in summaries | `keep search "OAuth"` |
-| `list` | List recent items by update time | `keep list` or `keep list -n 20` |
+| `list` | List recent item IDs | `keep list` or `keep --full list` |
 | `update` | Index content (URI, text, or stdin) | `keep update "note" -t key=value` |
-| `get` | Retrieve item by ID | `keep get "file:///path/to/doc.md"` |
+| `get` | Retrieve item (shows similar items) | `keep get "file:///path/to/doc.md"` |
+| `get --similar` | List similar items | `keep get ID --similar` or `-n 20` for more |
 | `get -V N` | Previous versions | `keep get ID -V 1` or `keep get ID --history` |
 | `tag` | List tag values or find by tag | `keep tag domain=auth` or `keep tag --list` |
 | `tag-update` | Modify tags on existing item | `keep tag-update "id" --tag key=value` |
-| `exists` | Check if item is indexed | `keep exists "id"` |
-| `system` | List system documents | `keep system` |
 | `collections` | List all collections | `keep collections` |
 | `init` | Initialize or verify store | `keep init` |
 | `config` | Show configuration and store path | `keep config` |
@@ -280,12 +295,13 @@ Default output uses YAML frontmatter format:
 ```yaml
 ---
 id: file:///path/to/doc.md
-tags:
-  project: myapp
+tags: {project: myapp, domain: auth}
+similar:
+  - doc:related-auth (0.89)
+  - doc:token-notes (0.85)
 score: 0.823
 prev:
-  - 1: 2026-01-15 Previous summary...
-  - 2: 2026-01-14 Older summary...
+  - v1: 2026-01-15 Previous summary...
 ---
 Document summary here...
 ```
@@ -294,6 +310,7 @@ Global flags (before the command):
 ```bash
 keep --json find "auth"    # JSON output
 keep --ids find "auth"     # IDs only (for piping)
+keep --full list           # Full items (overrides IDs-only default)
 keep -v find "auth"        # Debug logging
 ```
 

{keep_skill-0.3.0 → keep_skill-0.4.1}/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_skill-0.3.0 → keep_skill-0.4.1}/keep/api.py

@@ -902,7 +902,66 @@ 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 query_fulltext(
         self,
         query: str,

{keep_skill-0.3.0 → keep_skill-0.4.1}/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,10 @@ 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 +43,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 +64,29 @@ 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,
 ) -> str:
     """
     Format item as YAML frontmatter with summary as content.
@@ -77,41 +94,58 @@ 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
+
+    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 similar items if available
+    if similar_items:
+        lines.append("similar:")
+        for sim_item in similar_items:
+            score_str = f"({sim_item.score:.2f})" if sim_item.score else ""
+            lines.append(f"  - {sim_item.id} {score_str}")
+
     # Add version navigation if available
     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
+            for i, v in enumerate(version_nav["prev"]):
+                # Offset for this prev item: current_offset + i + 1
+                prev_offset = current_offset + i + 1
                 date_part = v.created_at[:10] if v.created_at else "unknown"
                 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"]:
+            for i, v in enumerate(version_nav["next"]):
+                # Offset for this next item: current_offset - i - 1
+                next_offset = current_offset - i - 1
                 date_part = v.created_at[:10] if v.created_at else "unknown"
                 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("  - v0 (current)")
 
     lines.append("---")
     lines.append(item.summary)  # Summary IS the content
@@ -139,15 +173,27 @@ 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")
+        typer.echo(_format_item(
+            item,
+            as_json=_get_json_output(),
+            version_nav=version_nav,
+            similar_items=similar_items,
+        ))
 
 
 # -----------------------------------------------------------------------------
@@ -197,13 +243,21 @@ 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,
 ) -> 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
     """
     if _get_ids_output():
         return json.dumps(item.id) if as_json else item.id
@@ -215,17 +269,42 @@ 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": s.id, "score": s.score, "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)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
@@ -364,11 +443,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()
@@ -605,34 +695,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 +744,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 +803,21 @@ 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)
         typer.echo(_format_item(
             item,
             as_json=_get_json_output(),
             version_nav=version_nav,
+            similar_items=similar_items,
         ))
 
 
 @app.command()
 def get(
-    id: Annotated[str, typer.Argument(help="URI of item to retrieve")],
+    id: Annotated[str, typer.Argument(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 +826,177 @@ 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)
+
+        if _get_ids_output():
+            # Output IDs one per line
+            for item in similar_items:
+                typer.echo(item.id)
+        elif _get_json_output():
+            result = {
+                "id": actual_id,
+                "similar": [
+                    {
+                        "id": item.id,
+                        "score": item.score,
+                        "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:
+                    score_str = f"({item.score:.2f})" if item.score else ""
+                    summary_preview = item.summary[:50].replace("\n", " ")
+                    if len(item.summary) > 50:
+                        summary_preview += "..."
+                    typer.echo(f"  {item.id} {score_str} {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
+    if not no_similar and offset == 0:
+        similar_items = kp.get_similar_for_display(actual_id, limit=3, 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,
+        similar_items=similar_items,
     ))
 
 
-@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 +1084,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_skill-0.3.0 → keep_skill-0.4.1}/keep/store.py

@@ -382,6 +382,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 → keep_skill-0.4.1}/pyproject.toml

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