Release 0.42.0 - Interface refactor: unified put() and find()

Unified remember()+update() into put(content, uri, id, summary, tags).
Unified find()+find_similar()+query_fulltext() into find(query, similar_to, fulltext).
Security: error log 0o600, binary stdin handling, tag validation on all paths.
REST: unified POST /search, ValueError→400, include_hidden fixes.
Protocol: KeeperProtocol fully aligned with Keeper and RemoteKeeper.

Author: hughpyle

README.md

@@ -125,8 +125,8 @@ from keep import Keeper
 kp = Keeper()
 
 # Index
-kp.update("file:///path/to/doc.md", tags={"project": "myapp"})
-kp.remember("Rate limit is 100 req/min", tags={"topic": "api"})
+kp.put(uri="file:///path/to/doc.md", tags={"project": "myapp"})
+kp.put("Rate limit is 100 req/min", tags={"topic": "api"})
 
 # Search
 results = kp.find("rate limit", limit=5)

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keep
-version: 0.41.0
+version: 0.42.0
 description: Reflective Memory
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim

docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ The original document content is **not stored** — only the summary and embeddi
 ┌─────────────────────────────────────────────────────────────┐
 │  API Layer (api.py)                                         │
 │  - Keeper class                                             │
-│  - High-level operations: update(), remember(), find()      │
+│  - High-level operations: put(), find(), get()              │
 │  - Version management: get_version(), list_versions()       │
 └──────────────────┬──────────────────────────────────────────┘
                    │
@@ -83,7 +83,7 @@ The original document content is **not stored** — only the summary and embeddi
 
 ## Data Flow
 
-### Indexing: update(uri) or remember(content)
+### Indexing: put(uri=...) or put(content)
 
 ```
 URI or content
@@ -200,7 +200,7 @@ delete(id)
 
 **5. Immutable Items**
 - `Item` is frozen dataclass
-- Updates via `update()` return new Item
+- Updates via `put()` return new Item
 - Prevents accidental mutation bugs
 
 **6. System Tag Protection**
@@ -313,7 +313,7 @@ Generate text descriptions from media files, enriching metadata-only content.
 - **mlx**: Apple Silicon — vision (mlx-vlm) + audio transcription (mlx-whisper)
 - **ollama**: Local server — vision models only (llava, moondream, bakllava)
 
-Media description runs in `Keeper.update()` between fetch and upsert. Descriptions are appended to the metadata content before embedding/summarization, making media files semantically searchable by their visual or audio content.
+Media description runs in `Keeper.put()` between fetch and upsert. Descriptions are appended to the metadata content before embedding/summarization, making media files semantically searchable by their visual or audio content.
 
 Design points:
 - Only triggered for non-text content types (image/*, audio/*)
@@ -373,7 +373,7 @@ Design points:
 - Lazy loading prevents import-time crashes
 
 **URI Fetch Failures**
-- `update()` raises `IOError` for unreachable URIs
+- `put()` raises `IOError` for unreachable URIs
 - Original error preserved in exception chain
 
 **Invalid Config**

docs/OUTPUT.md

@@ -18,11 +18,15 @@ meta/todo:                                                # 5. Meta sections
   - %b7c8d9e0 update auth docs for new flow
 meta/learnings:
   - %f1a2b3c4 Token refresh needs clock sync
-prev:                                                     # 6. Version navigation
+parts:                                                    # 6. Parts (structural)
+  - @P{1}  OAuth2 Flow Design (§1, pp.1-7)
+  - @P{2}  Token Storage Strategy (§2, pp.8-13)
+  - @P{3}  Session Management (§3, pp.14-18)
+prev:                                                     # 7. Version navigation
   - @V{1} 2026-01-14 Previous version of this item...
   - @V{2} 2026-01-13 Older version...
 ---
-I'll fix the auth bug by Friday                           # 7. Content
+I'll fix the auth bug by Friday                           # 8. Content
 ```
 
 ## Sections
@@ -92,7 +96,22 @@ These are dynamically resolved — the same item shows different meta sections d
 
 See [META-DOCS.md](META-DOCS.md) for how meta-docs work and how to create custom ones.
 
-### 6. `prev:` / `next:` — Version navigation
+### 6. `parts:` — Structural decomposition
+
+Sections of a document identified by `keep analyze`. Each line:
+
+```
+  - @P{N}  Section summary...
+```
+
+- **`@P{N}`** — part number (1-indexed). Use with `keep get "ID@P{1}"` to view a specific part.
+- Parts have their own tags, embeddings, and similar items — they appear independently in search results.
+- Only appears when a note has been analyzed. View all parts with `keep get ID --parts`.
+- Parts are the structural counterpart to versions: versions are temporal (`@V{N}`), parts are spatial (`@P{N}`).
+
+See [KEEP-ANALYZE.md](KEEP-ANALYZE.md) for how to decompose documents into parts.
+
+### 7. `prev:` / `next:` — Version navigation
 
 Navigate through the item's version history.
 
@@ -108,7 +127,7 @@ prev:
 
 See [VERSIONING.md](VERSIONING.md) for full versioning details.
 
-### 7. Content (after `---`)
+### 8. Content (after `---`)
 
 The item's summary, below the closing `---`. For short content this is the full text; for long documents it's a generated summary.
 

docs/PYTHON-API.md

@@ -18,9 +18,9 @@ from keep import Keeper
 kp = Keeper()  # Uses ~/.keep/ by default
 
 # Index documents
-kp.update("file:///path/to/doc.md", tags={"project": "myapp"})
-kp.update("https://example.com/page", tags={"topic": "reference"})
-kp.remember("Important insight about auth patterns")
+kp.put(uri="file:///path/to/doc.md", tags={"project": "myapp"})
+kp.put(uri="https://example.com/page", tags={"topic": "reference"})
+kp.put("Important insight about auth patterns")
 
 # Search
 results = kp.find("authentication", limit=5)
@@ -59,38 +59,36 @@ kp = Keeper(store_path="/path/to/store")
 
 ```python
 # Index from URI (file:// or https://)
-kp.update(uri, tags={}, summary=None) → Item
+kp.put(uri=uri, tags={}, summary=None) → Item
 
 # Index inline content
-kp.remember(content, summary=None, tags={}) → Item
+kp.put(content, tags={}, summary=None) → Item
 
 # Notes:
+# - Exactly one of content or uri must be provided
 # - If summary provided, skips auto-summarization
-# - remember() uses content verbatim if short (≤max_summary_length)
+# - Inline content used verbatim if short (≤max_summary_length)
 # - User tags (domain, topic, etc.) provide context for summarization
 ```
 
 #### Search
 
 ```python
-# Semantic search
-kp.find(query, limit=10, since=None) → list[Item]
+# Semantic search (default)
+kp.find("auth", limit=10) → list[Item]
 
-# Find similar to a document
-kp.find_similar(uri, limit=10, since=None) → list[Item]
+# Full-text search
+kp.find("auth", fulltext=True) → list[Item]
 
-# Similar items using stored embedding
-kp.get_similar_for_display(id, limit=3) → list[Item]
+# Find similar to an existing note
+kp.find(similar_to="note-id", limit=10) → list[Item]
 
 # Tag-based query
 kp.query_tag(key, value=None, since=None) → list[Item]
 
-# Full-text search
-kp.query_fulltext(query, since=None) → list[Item]
-
 # Time filtering (all search methods support since)
 kp.find("auth", since="P7D")      # Last 7 days
-kp.find("auth", since="P1W")      # Last week  
+kp.find("auth", since="P1W")      # Last week
 kp.find("auth", since="PT1H")     # Last hour
 kp.find("auth", since="2026-01-15")  # Since date
 ```
@@ -192,7 +190,7 @@ When indexing, tags merge in priority order (later wins):
 1. Existing tags (from previous version)
 2. Config tags (from `[tags]` in keep.toml)
 3. Environment tags (from `KEEP_TAG_*` variables)
-4. User tags (passed to `update()`, `remember()`, or `tag()`)
+4. User tags (passed to `put()` or `tag()`)
 
 ### Tag Rules
 
@@ -207,7 +205,7 @@ import os
 os.environ["KEEP_TAG_PROJECT"] = "myapp"
 os.environ["KEEP_TAG_OWNER"] = "alice"
 
-kp.remember("note")  # Auto-tagged with project=myapp, owner=alice
+kp.put("note")  # Auto-tagged with project=myapp, owner=alice
 ```
 
 ### Config Tags

docs/REFERENCE.md

@@ -152,13 +152,13 @@ See [PYTHON-API.md](PYTHON-API.md) for complete Python API reference.
 ```python
 from keep import Keeper
 kp = Keeper()
-kp.remember("note", tags={"project": "myapp"})
+kp.put("note", tags={"project": "myapp"})
 results = kp.find("authentication", limit=5)
 ```
 
 ## When to Use
-- `put` / `update()` — when referencing any file/URL worth remembering
-- `put` / `remember()` — capture conversation insights, decisions, notes
+- `put` / `put(uri=...)` — when referencing any file/URL worth remembering
+- `put` / `put("text")` — capture conversation insights, decisions, notes
 - `find` — before searching filesystem; may already be indexed
 - `find --since` — filter to recent items when recency matters
 

docs/SYSTEM-TAGS.md

@@ -54,7 +54,7 @@ These tags are actively set and maintained by the system.
 
 **Set by:** `_record_to_item()` in `api.py`, from `accessed_at` column in `DocumentStore`
 
-**Behavior:** Updated whenever the item is retrieved via `get()`, `find()`, `find_similar()`, or `query_fulltext()`. Distinct from `_updated` — reading an item updates `_accessed` but not `_updated`.
+**Behavior:** Updated whenever the item is retrieved via `get()` or `find()`. Distinct from `_updated` — reading an item updates `_accessed` but not `_updated`.
 
 **Example:** `"2026-02-07T09:15:00.123456+00:00"`
 
@@ -78,25 +78,25 @@ These tags are actively set and maintained by the system.
 
 **Purpose:** MIME type of the document content.
 
-**Set by:** `Keeper.update()` in `api.py` (only for URI-based documents)
+**Set by:** `Keeper.put()` in `api.py` (only for URI-based documents)
 
 **Behavior:** Set if the document provider returns a content type.
 
 **Example:** `"text/markdown"`, `"text/html"`, `"application/pdf"`, `"audio/mpeg"`, `"image/jpeg"`
 
-**Note:** Not set for inline content (CLI: `keep put "text"`, API: `kp.remember()`).
+**Note:** Not set for inline content (CLI: `keep put "text"`, API: `kp.put("text")`).
 
 ---
 
 ### `_source`
 
 **Purpose:** How the content was obtained.
 
-**Set by:** `Keeper.update()` and `Keeper.remember()` in `api.py`
+**Set by:** `Keeper.put()` in `api.py`
 
 **Values:**
-- `"uri"` - Content fetched from a URI (CLI: `keep put <uri>`, API: `kp.update()`)
-- `"inline"` - Inline content (CLI: `keep put "text"`, API: `kp.remember()`)
+- `"uri"` - Content fetched from a URI (CLI: `keep put <uri>`, API: `kp.put(uri=...)`)
+- `"inline"` - Inline content (CLI: `keep put "text"`, API: `kp.put("text")`)
 
 **Usage:** Query with `kp.query_tag("_source", "inline")` to find remembered content.
 
@@ -115,7 +115,7 @@ def filter_non_system_tags(tags: dict[str, str]) -> dict[str, str]:
     return {k: v for k, v in tags.items() if not k.startswith(SYSTEM_TAG_PREFIX)}
 ```
 
-This function is called before merging user-provided tags in `update()` (API), `remember()` (API), and `tag()` methods.
+This function is called before merging user-provided tags in `put()` and `tag()` methods.
 
 ## Tag Merge Order
 
@@ -124,7 +124,7 @@ When indexing documents, tags are merged in this order (later wins on collision)
 1. **Existing tags** - Preserved from previous version
 2. **Config tags** - From `[tags]` section in `keep.toml`
 3. **Environment tags** - From `KEEP_TAG_*` variables
-4. **User tags** - Passed to `update()`, `remember()`, or `tag()`
+4. **User tags** - Passed to `put()` or `tag()`
 5. **System tags** - Added/updated by system (cannot be overridden)
 
 ## Querying by System Tags

keep/__init__.py

@@ -8,7 +8,7 @@
     from keep import Keeper
 
     kp = Keeper()
-    kp.update("file:///path/to/document.md", source_tags={"project": "myproject"})
+    kp.put(uri="file:///path/to/document.md", tags={"project": "myproject"})
     results = kp.find("something similar to this query")
 
 CLI Usage:
@@ -37,7 +37,7 @@
 )
 from .types import Item, filter_non_system_tags, SYSTEM_TAG_PREFIX, INTERNAL_TAGS
 
-__version__ = "0.41.0"
+__version__ = "0.42.0"
 __all__ = [
     "Keeper",
     "Item",