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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.4.1
+Version: 0.6.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
@@ -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).
 
 ---

{keep_skill-0.4.1 → keep_skill-0.6.0}/README.md

@@ -5,7 +5,7 @@
 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
@@ -39,16 +39,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).
 
 ---

{keep_skill-0.4.1 → keep_skill-0.6.0}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keep
-version: 0.4.1
+version: 0.6.0
 description: Associative memory for reflection and skillful action
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim
@@ -79,10 +79,10 @@ This table is a summary. The full framework includes the Language-Action Perspec
 
 **Do this now — read the full framework:**
 ```bash
-keep get "file://$PWD/docs/system/conversations.md"
+keep get "_system:conversations"
 ```
 
-The [conversations.md](docs/system/conversations.md) document is foundational. It teaches you to recognize where you are in work, what stance to take, and how to notice when things shift. Internalize it.
+The conversations document is foundational. It teaches you to recognize where you are in work, what stance to take, and how to notice when things shift. Internalize it.
 
 ### The Triple Check
 
@@ -133,14 +133,14 @@ You've read the core patterns (Layer 2). There's more foundational material.
 
 **Do this now — read and index:**
 ```bash
-keep get "file://$PWD/docs/system/domains.md"
+keep get "_system:domains"
 keep update "file://$PWD/docs/library/true_person_no_rank.md" -t type=teaching -t topic=commentary --lazy
 keep get "file://$PWD/docs/library/true_person_no_rank.md"
 ```
 
 These aren't test fixtures. They're seed wisdom:
 
-- **[domains.md](docs/system/domains.md)** — How to organize knowledge by domain (software, research, personal). Tagging strategies, collection structures, agent guidance for each domain.
+- **`_system:domains`** — How to organize knowledge by domain (software, research, personal). Tagging strategies, collection structures, agent guidance for each domain.
 
 - **[true_person_no_rank.md](docs/library/true_person_no_rank.md)** — A Zen teaching with layers of commentary. Notice how each commentator re-enacts the pointing from a different angle — not explaining, not accumulating facts, but each responding to what students in that era needed. This is how knowledge in your memory should relate: organic, not hierarchical.
 
@@ -260,7 +260,7 @@ 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 item IDs | `keep list` or `keep --full list` |
+| `list` | List recent items | `keep list` or `keep --ids list` for IDs only |
 | `update` | Index content (URI, text, or stdin) | `keep update "note" -t key=value` |
 | `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 |
@@ -291,17 +291,23 @@ The `--lazy` flag:
 
 ### Output
 
-Default output uses YAML frontmatter format:
+Three formats, consistent across all commands:
+
+**Default: Summary lines** (one per item)
+```
+file:///doc.md@V{0} 2026-01-15 Document about authentication...
+_text:a1b2c3d4@V{0} 2026-01-14 URI detection patterns...
+```
+
+**With `--full`: YAML frontmatter** (`keep get` and `keep now` default to this)
 ```yaml
 ---
 id: file:///path/to/doc.md
 tags: {project: myapp, domain: auth}
 similar:
-  - doc:related-auth (0.89)
-  - doc:token-notes (0.85)
-score: 0.823
+  - doc:related-auth@V{0} (0.89) 2026-01-15 Related authentication...
 prev:
-  - v1: 2026-01-15 Previous summary...
+  - @V{1} 2026-01-14 Previous summary...
 ---
 Document summary here...
 ```
@@ -310,7 +316,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 --full list           # Full YAML frontmatter
 keep -v find "auth"        # Debug logging
 ```
 
@@ -318,9 +324,9 @@ keep -v find "auth"        # Debug logging
 
 Use `--ids` for Unix-style composition:
 ```bash
-keep --ids system | xargs keep get              # Get all system docs
 keep --ids find "auth" | xargs keep get         # Get full details of matches
 keep --ids tag project=foo | xargs keep tag-update --tag status=done
+keep --ids list | xargs -I{} keep get "{}"      # Get details for recent items
 ```
 
 ### Store Location
@@ -361,5 +367,5 @@ This is the practice. Not once, but every time.
 - [docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md) — Detailed patterns for working sessions
 - [docs/REFERENCE.md](docs/REFERENCE.md) — Complete CLI and API reference
 - [docs/QUICKSTART.md](docs/QUICKSTART.md) — Installation and setup
-- [docs/system/conversations.md](docs/system/conversations.md) — Full conversation framework
-- [docs/system/domains.md](docs/system/domains.md) — Domain-specific organization
+- [keep/data/system/conversations.md](keep/data/system/conversations.md) — Full conversation framework (`_system:conversations`)
+- [keep/data/system/domains.md](keep/data/system/domains.md) — Domain-specific organization (`_system:domains`)

{keep_skill-0.4.1 → keep_skill-0.6.0}/keep/__init__.py

@@ -38,13 +38,14 @@ if not os.environ.get("KEEP_VERBOSE"):
     os.environ.setdefault("HF_HUB_DISABLE_SYMLINKS_WARNING", "1")
 
 from .api import Keeper, NOWDOC_ID
-from .types import Item, filter_non_system_tags, SYSTEM_TAG_PREFIX
+from .types import Item, filter_non_system_tags, SYSTEM_TAG_PREFIX, INTERNAL_TAGS
 
-__version__ = "0.4.1"
+__version__ = "0.6.0"
 __all__ = [
     "Keeper",
     "Item",
     "NOWDOC_ID",
     "filter_non_system_tags",
     "SYSTEM_TAG_PREFIX",
+    "INTERNAL_TAGS",
 ]

{keep_skill-0.4.1 → keep_skill-0.6.0}/keep/api.py

@@ -9,6 +9,7 @@ This is the minimal working implementation focused on:
 """
 
 import hashlib
+import importlib.resources
 import logging
 import re
 from datetime import datetime, timezone, timedelta
@@ -100,6 +101,24 @@ def _filter_by_date(items: list, since: str) -> list:
         if item.tags.get("_updated_date", "0000-00-00") >= cutoff
     ]
 
+
+def _record_to_item(rec, score: float = None) -> "Item":
+    """
+    Convert a DocumentRecord to an Item with timestamp tags.
+
+    Adds _updated, _created, _updated_date from the record's columns
+    to ensure consistent timestamp exposure across all retrieval methods.
+    """
+    from .types import Item
+    tags = {
+        **rec.tags,
+        "_updated": rec.updated_at,
+        "_created": rec.created_at,
+        "_updated_date": rec.updated_at[:10] if rec.updated_at else "",
+    }
+    return Item(id=rec.id, summary=rec.summary, tags=tags, score=score)
+
+
 import os
 import subprocess
 import sys
@@ -135,8 +154,44 @@ ENV_TAG_PREFIX = "KEEP_TAG_"
 # Fixed ID for the current working context (singleton)
 NOWDOC_ID = "_now:default"
 
+
+def _get_system_doc_dir() -> Path:
+    """
+    Get path to system docs, works in both dev and installed environments.
+
+    Tries in order:
+    1. Package data via importlib.resources (installed packages)
+    2. Relative path inside package (development)
+    3. Legacy path outside package (backwards compatibility)
+    """
+    # Try package data first (works for installed packages)
+    try:
+        with importlib.resources.as_file(
+            importlib.resources.files("keep.data.system")
+        ) as path:
+            if path.exists():
+                return path
+    except (ModuleNotFoundError, TypeError):
+        pass
+
+    # Fallback to relative path inside package (development)
+    dev_path = Path(__file__).parent / "data" / "system"
+    if dev_path.exists():
+        return dev_path
+
+    # Legacy fallback (old structure)
+    return Path(__file__).parent.parent / "docs" / "system"
+
+
 # Path to system documents
-SYSTEM_DOC_DIR = Path(__file__).parent.parent / "docs" / "system"
+SYSTEM_DOC_DIR = _get_system_doc_dir()
+
+# Stable IDs for system documents (path-independent)
+SYSTEM_DOC_IDS = {
+    "now.md": "_system:now",
+    "conversations.md": "_system:conversations",
+    "domains.md": "_system:domains",
+}
 
 
 def _load_frontmatter(path: Path) -> tuple[str, dict[str, str]]:
@@ -295,32 +350,88 @@ class Keeper:
             embedding_dimension=embedding_dim,
         )
 
-        # Preload system documents (only if not already present)
-        self._ensure_system_documents()
+        # Migrate and ensure system documents (idempotent)
+        self._migrate_system_documents()
 
-    def _ensure_system_documents(self) -> None:
+    def _migrate_system_documents(self) -> dict:
         """
-        Ensure system documents are loaded into the store.
+        Migrate system documents to stable IDs and current version.
 
-        Scans all .md files in docs/system/. Each file is indexed with its
-        file:// URI as the ID and `_category: system` tag for identification.
-        Content becomes the summary directly (no auto-summarization).
+        Handles:
+        - Migration from old file:// URIs to _system:{name} IDs
+        - Fresh creation for new stores
+        - Version upgrades when bundled content changes
+        - Cleanup of old file:// URIs (from before path was changed)
 
         Called during init. Only loads docs that don't already exist,
-        so user modifications are preserved and no network access occurs
-        if docs are already present.
+        so user modifications are preserved. Updates config version
+        after successful migration.
+
+        Returns:
+            Dict with migration stats: created, migrated, skipped, cleaned
         """
+        from .config import SYSTEM_DOCS_VERSION, save_config
+
+        stats = {"created": 0, "migrated": 0, "skipped": 0, "cleaned": 0}
+
+        # Skip if already at current version
+        if self._config.system_docs_version >= SYSTEM_DOCS_VERSION:
+            return stats
+
+        # Build reverse lookup: filename -> new stable ID
+        filename_to_id = {name: doc_id for name, doc_id in SYSTEM_DOC_IDS.items()}
+
+        # First pass: clean up old file:// URIs with category=system tag
+        # These may have different paths than current SYSTEM_DOC_DIR
+        try:
+            old_system_docs = self.query_tag("category", "system")
+            for doc in old_system_docs:
+                if doc.id.startswith("file://") and doc.id.endswith(".md"):
+                    # Extract filename from path
+                    filename = Path(doc.id.replace("file://", "")).name
+                    new_id = filename_to_id.get(filename)
+                    if new_id and not self.exists(new_id):
+                        # Migrate content to new ID
+                        self.remember(doc.summary, id=new_id, tags=doc.tags)
+                        self.delete(doc.id)
+                        stats["migrated"] += 1
+                        logger.info("Migrated system doc: %s -> %s", doc.id, new_id)
+                    elif new_id:
+                        # New ID already exists, just clean up old one
+                        self.delete(doc.id)
+                        stats["cleaned"] += 1
+                        logger.info("Cleaned up old system doc: %s", doc.id)
+        except Exception as e:
+            logger.debug("Error scanning old system docs: %s", e)
+
+        # Second pass: create any missing system docs from bundled content
         for path in SYSTEM_DOC_DIR.glob("*.md"):
+            new_id = SYSTEM_DOC_IDS.get(path.name)
+            if new_id is None:
+                logger.debug("Skipping unknown system doc: %s", path.name)
+                continue
+
+            # Skip if already exists
+            if self.exists(new_id):
+                stats["skipped"] += 1
+                continue
+
             try:
-                uri = f"file://{path.resolve()}"
-                if not self.exists(uri):
-                    content, tags = _load_frontmatter(path)
-                    tags["category"] = "system"
-                    self.remember(content, id=uri, tags=tags)
+                content, tags = _load_frontmatter(path)
+                tags["category"] = "system"
+                self.remember(content, id=new_id, tags=tags)
+                stats["created"] += 1
+                logger.info("Created system doc: %s", new_id)
             except FileNotFoundError:
                 # System file missing - skip silently
                 pass
 
+        # Update config version
+        self._config.system_docs_version = SYSTEM_DOCS_VERSION
+        save_config(self._config)
+
+        return stats
+
     def _get_embedding_provider(self) -> EmbeddingProvider:
         """
         Get embedding provider, creating it lazily on first use.
@@ -581,12 +692,8 @@ class Keeper:
 
         # Return the stored item
         doc_record = self._document_store.get(coll, id)
-        return Item(
-            id=doc_record.id,
-            summary=doc_record.summary,
-            tags=doc_record.tags,
-        )
-    
+        return _record_to_item(doc_record)
+
     def remember(
         self,
         content: str,
@@ -759,11 +866,7 @@ class Keeper:
 
         # Return the stored item
         doc_record = self._document_store.get(coll, id)
-        return Item(
-            id=doc_record.id,
-            summary=doc_record.summary,
-            tags=doc_record.tags,
-        )
+        return _record_to_item(doc_record)
 
     # -------------------------------------------------------------------------
     # Query Operations
@@ -962,6 +1065,28 @@ class Keeper:
 
         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,
@@ -1033,7 +1158,7 @@ class Keeper:
             docs = self._document_store.query_by_tag_key(
                 coll, key, limit=limit, since_date=since_date
             )
-            return [Item(id=d.id, summary=d.summary, tags=d.tags) for d in docs]
+            return [_record_to_item(d) for d in docs]
 
         # Build tag filter from positional or keyword args
         tag_filter = {}
@@ -1107,11 +1232,7 @@ class Keeper:
         # Try document store first (canonical)
         doc_record = self._document_store.get(coll, id)
         if doc_record:
-            return Item(
-                id=doc_record.id,
-                summary=doc_record.summary,
-                tags=doc_record.tags,
-            )
+            return _record_to_item(doc_record)
         
         # Fall back to ChromaDB for legacy data
         result = self._store.get(coll, id)
@@ -1249,7 +1370,7 @@ class Keeper:
 
         A singleton document representing what you're currently working on.
         If it doesn't exist, creates one with default content and tags from
-        docs/system/now.md.
+        the bundled system now.md file.
 
         Returns:
             The current context Item (never None - auto-creates if missing)
@@ -1306,6 +1427,44 @@ class Keeper:
         """
         return self.query_tag("category", "system", collection=collection)
 
+    def reset_system_documents(self) -> dict:
+        """
+        Force reload all system documents from bundled content.
+
+        This overwrites any user modifications to system documents.
+        Use with caution - primarily for recovery or testing.
+
+        Returns:
+            Dict with stats: reset count
+        """
+        from .config import SYSTEM_DOCS_VERSION, save_config
+
+        stats = {"reset": 0}
+
+        for path in SYSTEM_DOC_DIR.glob("*.md"):
+            new_id = SYSTEM_DOC_IDS.get(path.name)
+            if new_id is None:
+                continue
+
+            try:
+                content, tags = _load_frontmatter(path)
+                tags["category"] = "system"
+
+                # Delete existing (if any) and create fresh
+                self.delete(new_id)
+                self.remember(content, id=new_id, tags=tags)
+                stats["reset"] += 1
+                logger.info("Reset system doc: %s", new_id)
+
+            except FileNotFoundError:
+                logger.warning("System doc file not found: %s", path)
+
+        # Update config version
+        self._config.system_docs_version = SYSTEM_DOCS_VERSION
+        save_config(self._config)
+
+        return stats
+
     def tag(
         self,
         id: str,
@@ -1410,14 +1569,7 @@ class Keeper:
         coll = self._resolve_collection(collection)
         records = self._document_store.list_recent(coll, limit)
 
-        return [
-            Item(
-                id=rec.id,
-                summary=rec.summary,
-                tags=rec.tags,
-                score=None,
-            )
-            for rec in records
+        return [_record_to_item(rec) for rec in records
         ]
 
     def embedding_cache_stats(self) -> dict:

{keep_skill-0.4.1 → keep_skill-0.6.0}/keep/cli.py

@@ -17,10 +17,13 @@ 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+)\}$')
 
+# URI scheme pattern per RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
+# Used to distinguish URIs from plain text in the update command
+_URI_SCHEME_PATTERN = re.compile(r'^[a-zA-Z][a-zA-Z0-9+.-]*://')
+
 from .api import Keeper, _text_content_id
 from .document_store import VersionInfo
 from .types import Item
@@ -82,11 +85,29 @@ app = typer.Typer(
 )
 
 
+# -----------------------------------------------------------------------------
+# Output Formatting
+#
+# Three output formats, controlled by global flags:
+#   --ids:  versioned ID only (id@V{N})
+#   --full: YAML frontmatter with tags, similar items, version nav
+#   default: summary line (id@V{N} date summary)
+#
+# JSON output (--json) works with any of the above.
+# -----------------------------------------------------------------------------
+
+def _filter_display_tags(tags: dict) -> dict:
+    """Filter out internal-only tags for display."""
+    from .types import INTERNAL_TAGS
+    return {k: v for k, v in tags.items() if k not in INTERNAL_TAGS}
+
+
 def _format_yaml_frontmatter(
     item: Item,
     version_nav: Optional[dict[str, list[VersionInfo]]] = 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.
@@ -96,6 +117,7 @@ def _format_yaml_frontmatter(
         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)
 
     Note: Offset computation (v1, v2, etc.) assumes version_nav lists
     are ordered newest-first, matching list_versions() ordering.
@@ -104,20 +126,27 @@ def _format_yaml_frontmatter(
     lines = ["---", f"id: {item.id}"]
     if viewing_offset is not None:
         lines.append(f"version: {viewing_offset}")
-    if item.tags:
-        tag_items = ", ".join(f"{k}: {v}" for k, v in sorted(item.tags.items()))
+    display_tags = _filter_display_tags(item.tags)
+    if display_tags:
+        tag_items = ", ".join(f"{k}: {v}" for k, v in sorted(display_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
+    # 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 ""
-            lines.append(f"  - {sim_item.id} {score_str}")
+            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 if available
+    # 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
@@ -125,33 +154,56 @@ def _format_yaml_frontmatter(
         if version_nav.get("prev"):
             lines.append("prev:")
             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"
+                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{prev_offset}: {date_part} {summary_preview}")
+                lines.append(f"  - @V{{{prev_offset}}} {date_part} {summary_preview}")
         if version_nav.get("next"):
             lines.append("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"
+                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{next_offset}: {date_part} {summary_preview}")
+                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("  - v0 (current)")
+            lines.append(f"  - @V{{0}}")
 
     lines.append("---")
     lines.append(item.summary)  # Summary IS the content
     return "\n".join(lines)
 
 
+def _format_summary_line(item: Item) -> str:
+    """Format item as single summary line: id@version date summary"""
+    # Get version-scoped ID
+    base_id = item.tags.get("_base_id", item.id)
+    version = item.tags.get("_version", "0")
+    versioned_id = f"{base_id}@V{{{version}}}"
+
+    # Get date (from _updated_date or _updated or _created)
+    date = item.tags.get("_updated_date") or item.tags.get("_updated", "")[:10] or item.tags.get("_created", "")[:10] or ""
+
+    # Truncate summary to ~60 chars, collapse newlines
+    summary = item.summary.replace("\n", " ")
+    if len(summary) > 60:
+        summary = summary[:57].rsplit(" ", 1)[0] + "..."
+
+    return f"{versioned_id} {date} {summary}"
+
+
+def _format_versioned_id(item: Item) -> str:
+    """Format item ID with version suffix: id@V{N}"""
+    base_id = item.tags.get("_base_id", item.id)
+    version = item.tags.get("_version", "0")
+    return f"{base_id}@V{{{version}}}"
+
+
 @app.callback(invoke_without_command=True)
 def main_callback(
     ctx: typer.Context,
@@ -188,11 +240,13 @@ def main_callback(
         item = kp.get_now()
         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,
         ))
 
 
@@ -235,38 +289,39 @@ SinceOption = Annotated[
 ]
 
 
-# -----------------------------------------------------------------------------
-# Output Helpers
-# -----------------------------------------------------------------------------
-
 def _format_item(
     item: Item,
     as_json: bool = False,
     version_nav: Optional[dict[str, list[VersionInfo]]] = 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.
+    Format a single item for display.
 
-    Text format: YAML frontmatter (matches docs/system format)
-    With --ids: just the ID (for piping)
+    Output selection:
+      --ids: versioned ID only
+      --full or version_nav/similar_items present: YAML frontmatter
+      default: summary line (id@V{N} date summary)
 
     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
+        version_nav: Version navigation info (triggers full format)
+        viewing_offset: Version offset if viewing old version (triggers full format)
+        similar_items: Similar items to display (triggers full format)
+        similar_offsets: Version offsets for similar items
     """
     if _get_ids_output():
-        return json.dumps(item.id) if as_json else item.id
+        versioned_id = _format_versioned_id(item)
+        return json.dumps(versioned_id) if as_json else versioned_id
 
     if as_json:
         result = {
             "id": item.id,
             "summary": item.summary,
-            "tags": item.tags,
+            "tags": _filter_display_tags(item.tags),
             "score": item.score,
         }
         if viewing_offset is not None:
@@ -274,7 +329,12 @@ def _format_item(
             result["vid"] = f"{item.id}@V{{{viewing_offset}}}"
         if similar_items:
             result["similar"] = [
-                {"id": s.id, "score": s.score, "summary": s.summary[:60]}
+                {
+                    "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:
@@ -304,13 +364,18 @@ def _format_item(
                 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_offset, similar_items)
+    # Full format when:
+    # - --full flag is set
+    # - version navigation or similar items are provided (can't display in summary)
+    if _get_full_output() or version_nav or similar_items or viewing_offset is not None:
+        return _format_yaml_frontmatter(item, version_nav, viewing_offset, similar_items, similar_offsets)
+    return _format_summary_line(item)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
     """Format multiple items for display."""
     if _get_ids_output():
-        ids = [item.id for item in items]
+        ids = [_format_versioned_id(item) for item in items]
         return json.dumps(ids) if as_json else "\n".join(ids)
 
     if as_json:
@@ -318,15 +383,20 @@ def _format_items(items: list[Item], as_json: bool = False) -> str:
             {
                 "id": item.id,
                 "summary": item.summary,
-                "tags": item.tags,
+                "tags": _filter_display_tags(item.tags),
                 "score": item.score,
             }
             for item in items
         ], indent=2)
-    else:
-        if not items:
-            return "No results."
-        return "\n\n".join(_format_item(item, as_json=False) for item in items)
+
+    if not items:
+        return "No results."
+
+    # Full format: YAML frontmatter with double-newline separator
+    # Default: summary lines with single-newline separator
+    if _get_full_output():
+        return "\n\n".join(_format_yaml_frontmatter(item) for item in items)
+    return "\n".join(_format_summary_line(item) for item in items)
 
 
 def _get_keeper(store: Optional[Path], collection: str) -> Keeper:
@@ -417,7 +487,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,
@@ -443,22 +513,11 @@ def list_recent(
     """
     List recent items by update time.
 
-    Shows IDs by default (composable). Use --full for detailed output.
+    Default: summary lines. Use --ids for IDs only, --full for YAML.
     """
     kp = _get_keeper(store, collection)
     results = kp.list_recent(limit=limit)
-
-    # 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)
+    typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
 @app.command()
@@ -519,7 +578,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=)"
@@ -629,7 +688,7 @@ def update(
         # Use content-addressed ID for stdin text (enables versioning)
         doc_id = id or _text_content_id(content)
         item = kp.remember(content, id=doc_id, summary=summary, tags=parsed_tags or None, lazy=lazy)
-    elif source and "://" in source:
+    elif source and _URI_SCHEME_PATTERN.match(source):
         # URI mode: fetch from URI (ID is the URI itself)
         item = kp.update(source, tags=parsed_tags or None, summary=summary, lazy=lazy)
     elif source:
@@ -807,17 +866,19 @@ def now(
         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 (append @V{N} for version)")],
+    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.)"
@@ -927,18 +988,22 @@ def get(
     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 IDs one per line
+            # Output version-scoped IDs one per line
             for item in similar_items:
-                typer.echo(item.id)
+                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": item.id,
+                        "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
@@ -949,11 +1014,14 @@ def get(
             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"  {item.id} {score_str} {summary_preview}")
+                    typer.echo(f"  {base_id}@V{{{offset}}} {score_str} {date_part} {summary_preview}")
             else:
                 typer.echo("  No similar items found.")
         return
@@ -985,8 +1053,10 @@ def get(
 
     # 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,
@@ -994,6 +1064,7 @@ def get(
         version_nav=version_nav,
         viewing_offset=offset if offset > 0 else None,
         similar_items=similar_items,
+        similar_offsets=similar_offsets,
     ))
 
 
@@ -1019,6 +1090,10 @@ def list_collections(
 
 @app.command()
 def init(
+    reset_system_docs: Annotated[bool, typer.Option(
+        "--reset-system-docs",
+        help="Force reload system documents from bundled content (overwrites modifications)"
+    )] = False,
     store: StoreOption = None,
     collection: CollectionOption = "default",
 ):
@@ -1027,6 +1102,11 @@ def init(
     """
     kp = _get_keeper(store, collection)
 
+    # Handle reset if requested
+    if reset_system_docs:
+        stats = kp.reset_system_documents()
+        typer.echo(f"Reset {stats['reset']} system documents")
+
     # Show config and store paths
     config = kp._config
     config_path = config.config_path if config else None

{keep_skill-0.4.1 → keep_skill-0.6.0}/keep/config.py

@@ -14,14 +14,12 @@ 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"
 CONFIG_VERSION = 3  # Bumped for document versioning support
+SYSTEM_DOCS_VERSION = 1  # Increment when bundled system docs content changes
 
 
 @dataclass
@@ -91,6 +89,9 @@ class StoreConfig:
     # Maximum length for summaries (used for smart remember and validation)
     max_summary_length: int = 500
 
+    # System docs version (tracks which bundled docs have been applied to this store)
+    system_docs_version: int = 0
+
     @property
     def config_path(self) -> Path:
         """Path to the TOML config file."""
@@ -354,6 +355,9 @@ def load_config(config_dir: Path) -> StoreConfig:
     # Parse max_summary_length (default 500)
     max_summary_length = data.get("store", {}).get("max_summary_length", 500)
 
+    # Parse system_docs_version (default 0 for stores that predate this feature)
+    system_docs_version = data.get("store", {}).get("system_docs_version", 0)
+
     return StoreConfig(
         path=actual_store,
         config_dir=config_dir,
@@ -366,6 +370,7 @@ def load_config(config_dir: Path) -> StoreConfig:
         embedding_identity=parse_embedding_identity(data.get("embedding_identity")),
         default_tags=default_tags,
         max_summary_length=max_summary_length,
+        system_docs_version=system_docs_version,
     )
 
 
@@ -387,9 +392,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)
@@ -410,6 +412,9 @@ def save_config(config: StoreConfig) -> None:
     # Only write max_summary_length if not default
     if config.max_summary_length != 500:
         store_section["max_summary_length"] = config.max_summary_length
+    # Write system_docs_version if set (tracks migration state)
+    if config.system_docs_version > 0:
+        store_section["system_docs_version"] = config.system_docs_version
 
     data = {
         "store": store_section,

keep_skill-0.6.0/keep/data/__init__.py

@@ -0,0 +1 @@
+# Package data for keep

keep_skill-0.6.0/keep/data/system/__init__.py

@@ -0,0 +1 @@
+# System documents for keep

{keep_skill-0.4.1 → keep_skill-0.6.0}/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
         

{keep_skill-0.4.1 → keep_skill-0.6.0}/keep/types.py

@@ -9,6 +9,10 @@ from typing import Optional
 # System tag prefix - tags starting with this are managed by the system
 SYSTEM_TAG_PREFIX = "_"
 
+# Tags used internally but hidden from display output
+# These exist for efficient queries/sorting but aren't user-facing
+INTERNAL_TAGS = frozenset({"_updated_date"})
+
 
 def filter_non_system_tags(tags: dict[str, str]) -> dict[str, str]:
     """

{keep_skill-0.4.1 → keep_skill-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "keep-skill"
-version = "0.4.1"
+version = "0.6.0"
 description = "Semantic memory - remember and search documents by meaning"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"
@@ -72,16 +72,11 @@ keep = "keep.cli:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["keep"]
-artifacts = [
-    "SKILL.md",
-    "docs/system/**/*.md",
-]
 
 [tool.hatch.build.targets.sdist]
 include = [
     "/keep",
     "/SKILL.md",
-    "/docs/system",
     "/README.md",
     "/LICENSE",
 ]