keep-skill 0.6.0__py3-none-any.whl → 0.8.1__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:
@@ -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, INTERNAL_TAGS
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __all__ = [
     "Keeper",
     "Item",

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
@@ -269,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()
@@ -284,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.
@@ -1554,6 +1554,7 @@ class Keeper:
         self,
         limit: int = 10,
         *,
+        since: Optional[str] = None,
         collection: Optional[str] = None,
     ) -> list[Item]:
         """
@@ -1561,16 +1562,24 @@ class Keeper:
 
         Args:
             limit: Maximum number to return (default 10)
+            since: Only include items updated since (ISO duration like P3D, or date)
             collection: Collection to query (uses default if not specified)
 
         Returns:
             List of Items, most recently updated first
         """
         coll = self._resolve_collection(collection)
-        records = self._document_store.list_recent(coll, limit)
 
-        return [_record_to_item(rec) for rec in records
-        ]
+        # Fetch extra when filtering by date
+        fetch_limit = limit * 3 if since is not None else limit
+        records = self._document_store.list_recent(coll, fetch_limit)
+        items = [_record_to_item(rec) for rec in records]
+
+        # Apply date filter if specified
+        if since is not None:
+            items = _filter_by_date(items, since)
+
+        return items[:limit]
 
     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"
@@ -47,6 +47,7 @@ def _verbose_callback(value: bool):
 _json_output = False
 _ids_output = False
 _full_output = False
+_store_override: Optional[Path] = None
 
 
 def _json_callback(value: bool):
@@ -76,9 +77,19 @@ def _get_full_output() -> bool:
     return _full_output
 
 
+def _store_callback(value: Optional[Path]):
+    global _store_override
+    if value is not None:
+        _store_override = value
+
+
+def _get_store_override() -> Optional[Path]:
+    return _store_override
+
+
 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,
@@ -231,8 +242,15 @@ def main_callback(
         callback=_full_callback,
         is_eager=True,
     )] = False,
+    store: Annotated[Optional[Path], typer.Option(
+        "--store", "-s",
+        envvar="KEEP_STORE_PATH",
+        help="Path to the store directory",
+        callback=_store_callback,
+        is_eager=True,
+    )] = None,
 ):
-    """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
@@ -401,9 +419,10 @@ def _format_items(items: list[Item], as_json: bool = False) -> str:
 
 def _get_keeper(store: Optional[Path], collection: str) -> Keeper:
     """Initialize memory, handling errors gracefully."""
-    # store=None is fine — Keeper will use default (git root/.keep)
+    # Check global override from --store on main command
+    actual_store = store if store is not None else _get_store_override()
     try:
-        return Keeper(store, collection=collection)
+        return Keeper(actual_store, collection=collection)
     except Exception as e:
         typer.echo(f"Error: {e}", err=True)
         raise typer.Exit(1)
@@ -464,6 +483,7 @@ def find(
     """
     Find items using semantic similarity search.
 
+    \b
     Examples:
         keep find "authentication"              # Search by text
         keep find --id file:///path/to/doc.md   # Find similar to item
@@ -509,71 +529,76 @@ def list_recent(
         "--limit", "-n",
         help="Number of items to show"
     )] = 10,
-):
-    """
-    List recent items by update time.
-
-    Default: summary lines. Use --ids for IDs only, --full for YAML.
-    """
-    kp = _get_keeper(store, collection)
-    results = kp.list_recent(limit=limit)
-    typer.echo(_format_items(results, as_json=_get_json_output()))
-
-
-@app.command()
-def tag(
-    query: Annotated[Optional[str], typer.Argument(
-        help="Tag key to list values, or key=value to find docs"
+    tag: Annotated[Optional[list[str]], typer.Option(
+        "--tag", "-t",
+        help="Filter by tag (key or key=value, repeatable)"
+    )] = None,
+    tags: Annotated[Optional[str], typer.Option(
+        "--tags", "-T",
+        help="List tag keys (--tags=), or values for KEY (--tags=KEY)"
     )] = None,
-    list_keys: Annotated[bool, typer.Option(
-        "--list", "-l",
-        help="List all distinct tag keys"
-    )] = False,
-    store: StoreOption = None,
-    collection: CollectionOption = "default",
-    limit: LimitOption = 100,
     since: SinceOption = None,
 ):
     """
-    List tag values or find items by tag.
+    List recent items, filter by tags, or list tag keys/values.
 
+    \b
     Examples:
-        keep tag --list              # List all tag keys
-        keep tag project             # List values for 'project' tag
-        keep tag project=myapp       # Find docs with project=myapp
+        keep list                      # Recent items
+        keep list --tag foo            # Items with tag 'foo' (any value)
+        keep list --tag foo=bar        # Items with tag foo=bar
+        keep list --tag foo --tag bar  # Items with both tags
+        keep list --tags=              # List all tag keys
+        keep list --tags=foo           # List values for tag 'foo'
+        keep list --since P3D          # Items updated in last 3 days
     """
     kp = _get_keeper(store, collection)
 
-    # List all keys mode
-    if list_keys or query is None:
-        tags = kp.list_tags(None, collection=collection)
-        if _get_json_output():
-            typer.echo(json.dumps(tags))
-        else:
-            if not tags:
-                typer.echo("No tags found.")
-            else:
-                for t in tags:
-                    typer.echo(t)
-        return
-
-    # Check if query is key=value or just key
-    if "=" in query:
-        # key=value → find documents
-        key, value = query.split("=", 1)
-        results = kp.query_tag(key, value, limit=limit, since=since)
-        typer.echo(_format_items(results, as_json=_get_json_output()))
-    else:
-        # key only → list values
-        values = kp.list_tags(query, collection=collection)
+    # --tags mode: list keys or values
+    if tags is not None:
+        # Empty string means list all keys, otherwise list values for key
+        key = tags if tags else None
+        values = kp.list_tags(key, collection=collection)
         if _get_json_output():
             typer.echo(json.dumps(values))
         else:
             if not values:
-                typer.echo(f"No values for tag '{query}'.")
+                if key:
+                    typer.echo(f"No values for tag '{key}'.")
+                else:
+                    typer.echo("No tags found.")
             else:
                 for v in values:
                     typer.echo(v)
+        return
+
+    # --tag mode: filter items by tag(s)
+    if tag:
+        # Parse each tag as key or key=value
+        # Multiple tags require all to match (AND)
+        results = None
+        for t in tag:
+            if "=" in t:
+                key, value = t.split("=", 1)
+                matches = kp.query_tag(key, value, limit=limit, since=since, collection=collection)
+            else:
+                # Key only - find items with this tag key (any value)
+                matches = kp.query_tag(t, limit=limit, since=since, collection=collection)
+
+            if results is None:
+                results = {item.id: item for item in matches}
+            else:
+                # Intersect with previous results
+                match_ids = {item.id for item in matches}
+                results = {id: item for id, item in results.items() if id in match_ids}
+
+        items = list(results.values()) if results else []
+        typer.echo(_format_items(items[:limit], as_json=_get_json_output()))
+        return
+
+    # Default: recent items
+    results = kp.list_recent(limit=limit, since=since, collection=collection)
+    typer.echo(_format_items(results, as_json=_get_json_output()))
 
 
 @app.command("tag-update")
@@ -595,6 +620,7 @@ def tag_update(
 
     Does not re-process the document - only updates tags.
 
+    \b
     Examples:
         keep tag-update doc:1 --tag project=myapp
         keep tag-update doc:1 doc:2 --tag status=reviewed
@@ -665,12 +691,14 @@ def update(
     """
     Add or update a document in the store.
 
+    \b
     Three input modes (auto-detected):
       keep update file:///path       # URI mode: has ://
       keep update "my note"          # Text mode: content-addressed ID
       keep update -                  # Stdin mode: explicit -
       echo "pipe" | keep update      # Stdin mode: piped input
 
+    \b
     Text mode uses content-addressed IDs for versioning:
       keep update "my note"           # Creates _text:{hash}
       keep update "my note" -t done   # Same ID, new version (tag change)
@@ -737,6 +765,7 @@ def now(
     With no arguments, displays the current context.
     With content, replaces it.
 
+    \b
     Examples:
         keep now                         # Show current context
         keep now "What's important now"  # Update context
@@ -907,6 +936,7 @@ def get(
 
     Version identifiers: Append @V{N} to get a specific version.
 
+    \b
     Examples:
         keep get doc:1                  # Current version with similar items
         keep get doc:1 -V 1             # Previous version with prev/next nav

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.

keep/data/system/domains.md

@@ -145,17 +145,17 @@ Ask about scope before large changes." \
 **Temporal queries using system tags:**
 ```bash
 # Find items updated today
-keep tag _updated_date=2026-01-30
+keep list --tag _updated_date=2026-01-30
 
 # Find all inline content (from remember)
-keep tag _source=inline
+keep list --tag _source=inline
 ```
 
 **Progressive refinement:**
 ```bash
 # Start broad, then narrow
 keep find "authentication"
-keep tag module=auth
+keep list --tag module=auth
 ```
 
 ---
@@ -173,7 +173,7 @@ 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
+keep list --tag type=conversation_pattern
 ```
 
 See [conversations.md](conversations.md) for the full framework.

keep/data/system/now.md

@@ -5,8 +5,7 @@ tags:
 ---
 # Now
 
-This is top-of-mind right now.  Reminders for essential practice.
-(Keep this updated as you need)
+Now: reflect on this work using `keep`.
 
 **Before acting:**
 - Where are we in the conversation?
@@ -16,4 +15,4 @@ This is top-of-mind right now.  Reminders for essential practice.
 **After acting:**
 - What happened? `keep update "what I learned" -t context=learning`
 - What do I save? `keep update`
-- What now? `keep now "Current focus: ..."`
+- 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
@@ -27,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.6.0.dist-info → keep_skill-0.8.1.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.6.0
-Summary: Semantic memory - remember and search documents by meaning
+Version: 0.8.1
+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.
 
@@ -128,8 +128,8 @@ keep get "ID@V{1}"                     # Same as -V 1 (version identifier)
 keep get ID --history                  # All versions
 
 # Tags
-keep tag project=myapp                 # Find by tag
-keep tag --list                        # List all tags
+keep list --tag project=myapp          # Find by tag
+keep list --tags=                      # List all tag keys
 
 # Current context
 keep now                               # Show what you're working on
@@ -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.6.0.dist-info → keep_skill-0.8.1.dist-info}/RECORD

@@ -1,9 +1,9 @@
-keep/__init__.py,sha256=lAm_iUUxz76EanZYE5UviCD1p2OSQwUag4Q67EP4oKE,1617
+keep/__init__.py,sha256=yBK7jvbQmx9fRBGanICNgrQdyCQHzt5bNPp098Qvh9E,1621
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=Ja_9zKr0bDL2UyBDZ03HrQHYkI9mdOMxuQlstyxJzmo,64477
+keep/api.py,sha256=V_w4ahhgmgk10ehjs5JAvTct8wOvL8xsvW-nko_9Yjw,64858
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=P7oKtv3TFL5BZNEfwh6kAFuqoeeqFxfVYssjdg0RMLc,44761
-keep/config.py,sha256=gw_QMY0VkCVF6xi-B9zGvZSza4z2QtiJucqgZJF3Xqg,16227
+keep/cli.py,sha256=SAB4LEZrX08sDVBxYD1s_zo2WXTYJBwhZswlQdjVkQ8,46024
+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,13 +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=_ytiG1O-9fY39o_TOktzYaFxHZBcIfuYgGI_vKsEx30,2316
+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=vsPCNy-9k3g5KKIgG0MYL21m8qYV3tI0hMa9co6hffc,442
-keep/providers/__init__.py,sha256=GFX_12g9OdjmpFUkTekOQBOWvcRW2Ae6yidfVVW2SiI,1095
+keep/data/system/domains.md,sha256=EHE6zU2-lx7UeLqyOTmoWl1WVlvgRq3_QnFb_EZceEY,5584
+keep/data/system/now.md,sha256=GyQo_LizSIVKbj5q52q4ErV-nxz8rzUOlkILjgNu25s,388
+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
@@ -26,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.6.0.dist-info/METADATA,sha256=lTAvkxt0X4pgtkLVfqZMBOdeGKz_tqO6KMm-nM2egjU,6606
-keep_skill-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-keep_skill-0.6.0.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
-keep_skill-0.6.0.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
-keep_skill-0.6.0.dist-info/RECORD,,
+keep_skill-0.8.1.dist-info/METADATA,sha256=ClBi2sP1kofuCjyjM1UsO8Yo_ouw-XxhLPIpMyDcVjE,6042
+keep_skill-0.8.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+keep_skill-0.8.1.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
+keep_skill-0.8.1.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
+keep_skill-0.8.1.dist-info/RECORD,,