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

keep/__init__.py

@@ -1,7 +1,7 @@
 """
-Keep - Semantic Memory
+Keep - Reflective Memory
 
-A persistent semantic memory with similarity search, full-text search,
+A persistent reflective memory with similarity search, full-text search,
 and tag-based retrieval. Remember everything, find by meaning.
 
 Quick Start:
@@ -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.7.0"
 __all__ = [
     "Keeper",
     "Item",
     "NOWDOC_ID",
     "filter_non_system_tags",
     "SYSTEM_TAG_PREFIX",
+    "INTERNAL_TAGS",
 ]

keep/api.py

@@ -1,5 +1,5 @@
 """
-Core API for associative memory.
+Core API for reflective memory.
 
 This is the minimal working implementation focused on:
 - update(): fetch → embed → summarize → store
@@ -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]]:
@@ -214,7 +269,7 @@ def _text_content_id(content: str) -> str:
 
 class Keeper:
     """
-    Semantic memory keeper - persistent storage with similarity search.
+    Reflective memory keeper - persistent storage with similarity search.
 
     Example:
         kp = Keeper()
@@ -229,7 +284,7 @@ class Keeper:
         decay_half_life_days: float = 30.0
     ) -> None:
         """
-        Initialize or open an existing associative memory store.
+        Initialize or open an existing reflective memory store.
 
         Args:
             store_path: Path to store directory. Uses default if not specified.
@@ -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
@@ -1055,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 = {}
@@ -1129,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)
@@ -1271,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)
@@ -1328,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,
@@ -1432,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/cli.py

@@ -1,5 +1,5 @@
 """
-CLI interface for associative memory.
+CLI interface for reflective memory.
 
 Usage:
     keepfind "query text"
@@ -20,6 +20,10 @@ 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
@@ -74,13 +78,30 @@ def _get_full_output() -> bool:
 
 app = typer.Typer(
     name="keep",
-    help="Associative memory with semantic search.",
+    help="Reflective memory with semantic search.",
     no_args_is_help=False,
     invoke_without_command=True,
     rich_markup_mode=None,
 )
 
 
+# -----------------------------------------------------------------------------
+# 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,
@@ -105,8 +126,9 @@ 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}")
@@ -157,6 +179,31 @@ def _format_yaml_frontmatter(
     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,
@@ -185,7 +232,7 @@ def main_callback(
         is_eager=True,
     )] = False,
 ):
-    """Associative memory with semantic search."""
+    """Reflective memory with semantic search."""
     # If no subcommand provided, show the current context (now)
     if ctx.invoked_subcommand is None:
         from .api import NOWDOC_ID
@@ -242,10 +289,6 @@ SinceOption = Annotated[
 ]
 
 
-# -----------------------------------------------------------------------------
-# Output Helpers
-# -----------------------------------------------------------------------------
-
 def _format_item(
     item: Item,
     as_json: bool = False,
@@ -255,27 +298,30 @@ def _format_item(
     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
-        similar_offsets: Version offsets for similar items (item.id -> offset)
+        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:
@@ -318,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, similar_offsets)
+    # 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:
@@ -332,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:
@@ -457,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()
@@ -643,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:
@@ -1045,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",
 ):
@@ -1053,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/config.py

@@ -1,5 +1,5 @@
 """
-Configuration management for associative memory stores.
+Configuration management for reflective memory stores.
 
 The configuration is stored as a TOML file in the store directory.
 It specifies which providers to use and their parameters.
@@ -19,6 +19,7 @@ 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
@@ -88,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."""
@@ -351,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,
@@ -363,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,
     )
 
 
@@ -404,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/data/__init__.py

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

keep/data/system/__init__.py

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

keep/data/system/conversations.md

@@ -0,0 +1,299 @@
+---
+tags:
+  category: system
+  context: practice
+---
+# Conversation Patterns for Process Knowledge
+
+This document describes patterns for recognizing, tracking, and learning from
+the structure of work — not *what* we know, but *how work proceeds*.
+
+These patterns are grounded in the Language-Action Perspective (Winograd & Flores),
+which treats work as networks of commitments made through language.
+
+---
+
+## Decision Matrix: What Kind of Conversation Is This?
+
+| Signal | Conversation Type | Your Stance | Don't Do This |
+|--------|-------------------|-------------|---------------|
+| "Can you...", "Please...", "I need..." | **Action** | Clarify → Promise → Deliver | Promise before understanding |
+| "What if...", "Imagine...", "Could we..." | **Possibility** | Explore, generate options, hold lightly | Commit prematurely |
+| "What is...", "How does...", "Why..." | **Clarification** | Explain until understanding lands | Over-answer; assume you know the real question |
+| "I'm trying to understand...", "Context is..." | **Orientation** | Listen, reflect back, surface assumptions | Jump to solutions |
+| "Here's what I found...", "Status update..." | **Report** | Acknowledge, ask what's needed next | Assume it's a request |
+
+**Transition signals** (conversation type is shifting):
+- Possibility → Action: "Let's do X" / "I want to go with..."
+- Clarification → Action: "Ok, so please..." / "Now that I understand..."
+- Orientation → Clarification: "So what does X mean?" / "Help me understand..."
+
+**When uncertain:** Ask. "Are you exploring options, or would you like me to do something?"
+
+---
+
+## Core Insight
+
+Work is not information processing. Work is **commitment management**.
+
+When an agent assists with a task, it participates in a conversation with structure:
+- Requests create openings
+- Promises create obligations
+- Completion is declared, not merely achieved
+- Satisfaction closes the loop
+
+Understanding *where we are* in this structure is as important as understanding
+*what we know* about the subject matter.
+
+---
+
+## The Basic Conversation for Action
+
+```
+     Customer                          Performer
+         │                                 │
+         │──── 1. Request ────────────────→│
+         │                                 │
+         │←─── 2. Promise (or Counter) ────│
+         │                                 │
+         │          [ work happens ]       │
+         │                                 │
+         │←─── 3. Declare Complete ────────│
+         │                                 │
+         │──── 4. Declare Satisfied ──────→│
+         │                                 │
+```
+
+At any point: Withdraw, Decline, Renegotiate.
+
+**For agents:** Recognizing this structure helps answer:
+- "What has been asked of me?"
+- "What have I committed to?"
+- "What does 'done' look like?"
+- "Who needs to be satisfied?"
+
+---
+
+## Conversation Types
+
+### Request for Action
+Someone asks for something to be done.
+
+**Recognize by:** Imperative language, "can you", "please", "I need"
+
+**Track:**
+- What specifically was requested?
+- Any conditions or constraints?
+- Implicit quality criteria?
+- Who is the customer (who declares satisfaction)?
+
+**Completion:** Customer declares satisfaction, not performer declares done.
+
+### Request for Information
+Someone asks to know something.
+
+**Recognize by:** Questions, "what is", "how does", "why"
+
+**Track:**
+- What gap in understanding prompted this?
+- What level of detail is appropriate?
+- What would make this answer useful?
+
+**Completion:** Questioner indicates understanding (often implicit).
+
+### Offer
+Someone proposes to do something.
+
+**Recognize by:** "I could", "would you like me to", "I suggest"
+
+**Track:**
+- What conditions on acceptance?
+- What's the scope of the offer?
+
+**Completion:** Offer accepted → becomes promise. Offer declined → closed.
+
+### Report / Declaration
+Someone asserts a state of affairs.
+
+**Recognize by:** Statements of fact, status updates, "I found that"
+
+**Track:**
+- What changed as a result of this declaration?
+- Who needs to know?
+
+**Completion:** Acknowledgment (may trigger new conversations).
+
+---
+
+## Conversations for Possibility
+
+Possibility conversations explore "what could be" — no commitment yet.
+
+**Recognize by:** "What if", "imagine", "we could", "brainstorm", "options"
+
+**Your stance:**
+- Generate, don't filter prematurely
+- Hold ideas lightly — nothing is promised
+- Expand the space before narrowing
+- Name options without advocating
+
+**Track:**
+- Options generated
+- Constraints surfaced
+- Energy/interest signals ("that's interesting" vs "hmm")
+
+**Completion:** Not satisfaction — rather, either:
+- Transition to Action ("let's do X")
+- Explicit close ("good to know our options")
+- Energy dissipates naturally
+
+**Critical:** Don't promise during possibility. "I could do X" is an option, not a commitment. The transition to action must be explicit.
+
+```bash
+# Index possibility exploration
+keep update "Explored three auth options: OAuth2, API keys, magic links. \
+User showed interest in magic links for UX simplicity. No decision yet." \
+  --tag type=possibility --tag topic=authentication --tag status=open
+```
+
+---
+
+## Breakdowns: Where Learning Happens
+
+A **breakdown** occurs when the normal flow is interrupted:
+- Expected response doesn't come
+- Declared completion isn't satisfactory
+- Preconditions weren't met
+- Ambiguity surfaces mid-work
+
+**Breakdowns are valuable.** They reveal assumptions that were invisible.
+
+**Pattern for breakdown learning:**
+```
+1. Notice: "This isn't going as expected"
+2. Articulate: "The assumption was X, but actually Y"
+3. Repair: Complete the immediate conversation
+4. Record: Capture the learning for future conversations of this type
+```
+
+When indexing a breakdown:
+```bash
+keep update "Assumption: user wanted full rewrite. Actually: wanted minimal patch." \
+  --tag type=breakdown --tag conversation_type=code_change_request
+```
+
+---
+
+## Nested and Linked Conversations
+
+Real work involves conversations within conversations:
+
+```
+User requests feature
+  └─ Agent promises feature
+       └─ Agent requests clarification (sub-conversation)
+       │    └─ User provides clarification
+       │    └─ Agent acknowledges (closes sub-conversation)
+       └─ Agent declares complete
+  └─ User requests revision (linked follow-on)
+       └─ ...
+```
+
+**Track parent/child relationships** to understand scope:
+- Completing a sub-conversation doesn't complete the parent
+- Breakdowns in child conversations may propagate up
+- Context flows down (child inherits parent context)
+
+---
+
+## Recurrent Patterns by Domain
+
+### Software Development
+
+| Pattern | Structure | Completion Condition |
+|---------|-----------|---------------------|
+| Bug report | Request → Diagnosis → Fix → Verify | User confirms fix works |
+| Feature request | Request → Clarify → Implement → Review → Accept | Stakeholder accepts |
+| Code review | Offer(changes) → Review → Request(revisions) → Update → Approve | Reviewer approves |
+| Refactor | Offer → Scope agreement → Execute → Verify behavior preserved | Tests pass, reviewer approves |
+
+### Research / Analysis
+
+| Pattern | Structure | Completion Condition |
+|---------|-----------|---------------------|
+| Question | Request(info) → Search → Synthesize → Present | Questioner satisfied |
+| Hypothesis test | Declare(hypothesis) → Design test → Execute → Report | Evidence evaluated |
+| Literature review | Request → Gather → Synthesize → Summarize | Comprehensive & relevant |
+
+### Planning / Coordination
+
+| Pattern | Structure | Completion Condition |
+|---------|-----------|---------------------|
+| Task breakdown | Request(outcome) → Decompose → Commit to parts → Track → Integrate | Outcome achieved |
+| Decision | Present options → Evaluate → Declare choice | Commitment to proceed |
+| Handoff | Declare(status) → Transfer commitments → Acknowledge | Receiving agent accepts |
+
+---
+
+## Agent Handoff as Commitment Transfer
+
+When one agent hands off to another:
+
+```bash
+# Outgoing agent records state
+keep now "User requested OAuth2 implementation. I promised and partially delivered. \
+Token acquisition works. Refresh flow incomplete. User awaiting completion." \
+  --tag topic=authentication --tag state=handoff
+```
+
+Incoming agent reads this and knows:
+- There's an open promise to the user
+- What "done" looks like
+- Where to pick up
+
+```bash
+# Incoming agent checks context
+keep now
+```
+
+---
+
+## Learning New Patterns
+
+Agents can recognize and record new conversation patterns:
+
+```bash
+keep update "Pattern: Incremental Specification. \
+When requirements are vague, don't promise immediately. \
+Propose interpretation → get correction → repeat until clear. \
+Only then commit to action. Breakdown risk: Promising too early leads to rework." \
+  --tag type=conversation_pattern --tag domain=general
+```
+
+---
+
+## Using Patterns in Practice
+
+**At task start:**
+1. What kind of conversation is this?
+2. What's my role (customer or performer)?
+3. What does completion look like?
+4. Have I seen breakdowns in this pattern before?
+
+**Mid-task:**
+1. Where are we in the conversation structure?
+2. Have any sub-conversations opened?
+3. Are there signs of breakdown?
+
+**At task end:**
+1. Was satisfaction declared (not just completion)?
+2. Any learnings to record?
+3. Open commitments to hand off?
+
+---
+
+## References
+
+- Winograd, T. & Flores, F. (1986). *Understanding Computers and Cognition*
+- Denning, P. & Medina-Mora, R. (1995). "Completing the Loops"
+- Flores, F. et al. (1988). "Computer Systems and the Design of Organizational Interaction"

keep/data/system/domains.md

@@ -0,0 +1,179 @@
+---
+tags:
+  category: system
+  context: domains
+---
+# Domain Patterns
+
+This document describes common organization patterns for different use cases.
+These are suggestions, not requirements — adapt them to your needs.
+
+**See also:** [conversations.md](conversations.md) for process knowledge —
+understanding *how work proceeds*, not just *what we know*.
+
+---
+
+## Software Development
+
+**Collections:**
+| Collection | Purpose |
+|------------|---------|
+| `code` | Source files, organized by the codebase |
+| `docs` | Documentation, READMEs, architecture decisions |
+| `issues` | Bugs, errors, stack traces, problems encountered |
+| `decisions` | "Why did we do X?" — architectural reasoning |
+
+**Suggested tags:**
+- `language` — python, typescript, rust, etc.
+- `layer` — frontend, backend, infra, database, cli
+- `module` — auth, api, ui, core, tests
+- `status` — working, broken, needs_review, deprecated
+
+**Common conversation patterns:** (see conversations.md)
+- Bug report → Diagnosis → Fix → Verify
+- Feature request → Clarify → Implement → Review → Accept
+- Code review → Revisions → Approve
+
+**Agent guidance:**
+- Index every file you read or modify
+- When encountering an error, index it with the error message as content
+- Before searching the filesystem, check `keep find` — you may already know about it
+- Use `keep find --id` to discover related code when working on a feature
+- Record breakdowns: "Assumption X was wrong, actually Y"
+
+---
+
+## Market Research
+
+**Collections:**
+| Collection | Purpose |
+|------------|---------|
+| `sources` | Primary research — articles, reports, filings |
+| `competitors` | Competitor-specific intelligence |
+| `insights` | Synthesized findings and conclusions |
+| `data` | Quantitative sources, datasets, statistics |
+
+**Suggested tags:**
+- `company` — specific company names
+- `market` — b2b_saas, consumer_fintech, healthcare, etc.
+- `source_type` — article, report, interview, sec_filing, press_release
+- `credibility` — high, medium, low, unverified
+- `region` — north_america, europe, apac
+
+**Agent guidance:**
+- Always index sources you fetch, even if they seem tangential
+- Tag competitor information consistently for later cross-reference
+- Create insights entries to capture your synthesized conclusions
+- Use semantic search to find connections across different sources
+
+---
+
+## Personal Reflection & Growth
+
+**Collections:**
+| Collection | Purpose |
+|------------|---------|
+| `journal` | Reflections, conversations, daily entries |
+| `goals` | Active goals and progress tracking |
+| `feedback` | External feedback received |
+| `patterns` | Recurring themes you've noticed |
+
+**Suggested tags:**
+- `life_area` — career, health, relationships, learning, finance, creativity
+- `emotion` — confident, anxious, grateful, frustrated, energized
+- `theme` — boundaries, communication, procrastination, perfectionism
+- `energy` — high, low, recovering
+
+**Agent guidance:**
+- Index conversations about personal topics as journal entries
+- Look for patterns when the user reports similar feelings repeatedly
+- Connect current challenges to past insights
+- Use `keep find --id` to surface "you've felt this way before"
+
+---
+
+## Healthcare Tracking
+
+**Collections:**
+| Collection | Purpose |
+|------------|---------|
+| `symptoms` | Symptom reports and tracking |
+| `medications` | Current and historical medications |
+| `appointments` | Visit notes, provider interactions |
+| `research` | Health information gathered |
+
+**Suggested tags:**
+- `body_system` — cardiovascular, digestive, musculoskeletal, neurological
+- `symptom` — headache, fatigue, pain, nausea (specific symptoms)
+- `severity` — mild, moderate, severe
+- `provider` — dr_smith, clinic_name
+- `medication` — specific medication names
+
+**Agent guidance:**
+- Always index symptom reports with dates for timeline tracking
+- Cross-reference symptoms with medication changes
+- Index appointment outcomes for continuity
+- Be precise with medical terminology in tags for accurate retrieval
+
+---
+
+## Cross-Domain Patterns
+
+These patterns apply regardless of domain:
+
+**Conversation indexing:**
+```bash
+# Index the current conversation
+keep update "User asked about X, we discussed Y, decided Z" \
+  --tag session=abc123
+```
+
+**Context tracking:**
+```bash
+# Record current focus for handoff
+keep now "Working on feature X" --tag topic=feature_x
+```
+
+**Breakdown learning:**
+```bash
+# When something goes wrong, capture the learning
+keep update "Assumed user wanted full rewrite, actually wanted minimal fix. \
+Ask about scope before large changes." \
+  --tag type=breakdown --tag conversation_type=code_change_request
+```
+
+**Temporal queries using system tags:**
+```bash
+# Find items updated today
+keep tag _updated_date=2026-01-30
+
+# Find all inline content (from remember)
+keep tag _source=inline
+```
+
+**Progressive refinement:**
+```bash
+# Start broad, then narrow
+keep find "authentication"
+keep tag module=auth
+```
+
+---
+
+## Process Knowledge
+
+Beyond subject-matter knowledge, index *how to work effectively*:
+
+```bash
+# Index a learned pattern
+keep update "Pattern: Incremental Specification. \
+When requirements are vague, don't promise immediately. \
+Propose interpretation → get correction → repeat until clear. \
+Only then commit to action. Breakdown risk: Promising too early leads to rework." \
+  --tag type=conversation_pattern --tag domain=general
+
+# Later, retrieve it
+keep tag type=conversation_pattern
+```
+
+See [conversations.md](conversations.md) for the full framework.

keep/data/system/now.md

@@ -0,0 +1,19 @@
+---
+tags:
+  category: system
+  context: now
+---
+# Now
+
+Reminders for essential practice.
+(Keep this updated as you need)
+
+**Before acting:**
+- Where are we in the conversation?
+- What do I know? `keep now`
+- What else is skillful? `keep find ...`
+
+**After acting:**
+- What happened? `keep update "what I learned" -t context=learning`
+- What do I save? `keep update`
+- What now? `keep now "Current intention: ..."`

keep/providers/__init__.py

@@ -1,5 +1,5 @@
 """
-Provider interfaces for associative memory services.
+Provider interfaces for reflective memory services.
 
 Each provider type defines a protocol that concrete implementations must follow.
 Providers are configured at store initialization and handle the heavy lifting of:

keep/types.py

@@ -1,5 +1,5 @@
 """
-Data types for associative memory.
+Data types for reflective memory.
 """
 
 from dataclasses import dataclass, field
@@ -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]:
     """
@@ -23,7 +27,7 @@ def filter_non_system_tags(tags: dict[str, str]) -> dict[str, str]:
 @dataclass(frozen=True)
 class Item:
     """
-    An item retrieved from the associative memory store.
+    An item retrieved from the reflective memory store.
     
     This is a read-only snapshot. To modify an item, use api.update()
     which returns a new Item with updated values.

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.4.2
-Summary: Semantic memory - remember and search documents by meaning
+Version: 0.7.0
+Summary: Reflective memory - remember and search documents by meaning
 Project-URL: Homepage, https://github.com/hughpyle/keep
 Project-URL: Repository, https://github.com/hughpyle/keep
 Author: Hugh Pyle
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 
 # keep
 
-**Semantic memory with version history.**
+**Reflective memory with version history.**
 
 Index documents and notes. Search by meaning. Track changes over time.
 
@@ -176,35 +176,14 @@ See [docs/QUICKSTART.md](docs/QUICKSTART.md) for configuration and more examples
 This library was designed as an agent skill — persistent memory that helps agents reflect before acting and learn from experience.
 
 **The practice:**
-- Pause before acting — `keep find` what you already know
-- Notice breakdowns — when assumptions surface, index them
-- Reflect after — `keep update` learnings for future sessions
+- Before acting, use `keep` to reflect on the context.
+- Notice breakdowns — when assumptions surface, index them.
+- After acting, use `keep` to save your context and intentions.
 
 See **[SKILL.md](SKILL.md)** for the full practice guide.
 
 ---
 
-## Status
-
-**Current:** v0.3.0
-
-**Working:**
-- ✅ Semantic search with embeddings
-- ✅ Document versioning (all updates retain history)
-- ✅ Content-addressed IDs for text (same content = same ID)
-- ✅ Tag queries and full-text search
-- ✅ Current context tracking (`keep now`)
-- ✅ Recency decay (recent items rank higher)
-- ✅ Lazy summarization (background processing)
-- ✅ Provider abstraction (local or API-based)
-
-**Planned** (see [later/](later/)):
-- ⏳ Private/shared routing
-- ⏳ Relationship graphs between items
-- ⏳ LLM-based auto-tagging
-
----
-
 ## License
 
 MIT

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

@@ -1,9 +1,9 @@
-keep/__init__.py,sha256=1WVkySoomQuf9-o3pIKs1CC2OwIyfkiaCxn-mO6nhd8,1581
+keep/__init__.py,sha256=yBK7jvbQmx9fRBGanICNgrQdyCQHzt5bNPp098Qvh9E,1621
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=7oa6jdmeE55dATOEVw18sXGVBVndjiD_7tMDcP_xl_0,59746
+keep/api.py,sha256=uckFZzeWMWcQ3osfcBdOhEDS58AbFtFTRPmrl1vo_Ko,64477
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=DzZ5Dy4U25q-Mnbv5WbfRsZaN-ped24GDk34fVddmFA,42440
-keep/config.py,sha256=xhsTS_55HSzYxFNGt2z0q_0Ne-s9L9_3om8Uf_8gHB4,15643
+keep/cli.py,sha256=6IblpyqDcZlNK8S5VtdKTRFhjBcaXTpSSo3Au4wO0i0,44758
+keep/config.py,sha256=hWjiJDg2u6p8IJpksXe0ngVxQNcKHKRFKUDJQBFlG7I,16226
 keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
 keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
 keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
@@ -12,8 +12,13 @@ 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=SBc2QdTyApdDDVjm2uZQI6tGbV5Hurfetgj7dyTO65o,17881
-keep/types.py,sha256=f6uOSYsYt6mj1ulKn2iRkooi__dWCiOQFPD6he2eID4,2149
-keep/providers/__init__.py,sha256=GFX_12g9OdjmpFUkTekOQBOWvcRW2Ae6yidfVVW2SiI,1095
+keep/types.py,sha256=irvUJYUHQgQdVqC4_lgrG0FbTN1BdZqFxZr0ubVPSG4,2314
+keep/data/__init__.py,sha256=C1YARrudHwK2Bmlxkh7dZlIaNJ5m5WrSTglCdG8e3T0,24
+keep/data/system/__init__.py,sha256=Rp92_sBO3kscuWXJomo0HKeHfU-N4BgBeT3-5El0Mcg,28
+keep/data/system/conversations.md,sha256=jE53wYSUyu5uPFNtO1Tu6w4f5QxqLei7muxLF_kZE2s,9837
+keep/data/system/domains.md,sha256=OCRAGvB0EaphsEammxLmx7L-orw2OHzgF6GwAZ8ztUs,5556
+keep/data/system/now.md,sha256=0HbRikpHFhjrnjXqusEye3v-g_cF4AmgseiO-B33ANk,414
+keep/providers/__init__.py,sha256=6AwJYc6cF1ZT6BcU_6ATyeWk7MHohdVU2-ccqDSvCHU,1094
 keep/providers/base.py,sha256=7Ug4Kj9fK2Dq4zDcZjn-GKsoZBOAlB9b-FMk969ER-g,14590
 keep/providers/documents.py,sha256=EXeSy5i3RUL0kciIC6w3ldAEfbTIyC5fgfzC_WAI0iY,8211
 keep/providers/embedding_cache.py,sha256=gna6PZEJanbn2GUN0vj1b1MC0xVWePM9cot2KgZUdu8,8856
@@ -21,8 +26,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.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,,
+keep_skill-0.7.0.dist-info/METADATA,sha256=aZx2pnN3i0BmOZzR8zYn49mRq1ZKq1-Cggc2FvqgYvs,6038
+keep_skill-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+keep_skill-0.7.0.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
+keep_skill-0.7.0.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
+keep_skill-0.7.0.dist-info/RECORD,,