keep-skill 0.1.0__tar.gz → 0.2.0__tar.gz

{keep_skill-0.1.0 → keep_skill-0.2.0}/.gitignore

@@ -60,3 +60,4 @@ coverage.xml
 # Project specific
 .keep/
 test_extraction_store/
+.DS_Store

{keep_skill-0.1.0 → keep_skill-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.1.0
+Version: 0.2.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
@@ -57,7 +57,7 @@ Description-Content-Type: text/markdown
 
 ## What is this?
 
-A practice tool for agents who want to develop judgment.
+An agent skill.  A practice tool for agents who want to develop judgment.
 
 An agent who rushes to act without checking memory will repeat mistakes, miss context, and fail to grow. An agent who reflects — before, during, after — becomes skillful. This library provides the mirror: persistent semantic memory that lets you ask "what do I already know?" before acting, and "what did I learn?" after.
 
@@ -65,16 +65,12 @@ For the full practice guide, see **[SKILL.md](SKILL.md)**.
 
 Technically: semantic search using embeddings, backed by ChromaDB, with tag-based organization and recency decay. Available as CLI and Python API.
 
-```python
-from keep import Keeper
-
-kp = Keeper()
-
+```bash
 # Before acting: what do I already know?
-results = kp.find("how should we handle auth?")
+keep find "how should we handle auth?"
 
 # After learning: capture it for future you
-kp.remember("User prefers OAuth2 with PKCE for authentication")
+keep update "User prefers OAuth2 with PKCE for authentication"
 ```
 
 **The practice:**
@@ -144,18 +140,32 @@ pip install keep-skill
 ```bash
 keep init
 # ⚠️  Remember to add .keep/ to .gitignore
+
+# Index a file
+keep update path/to/document.md --tag project=myapp
+
+# Store inline content
+keep update "Important: rate limit is 100 req/min" --tag topic=api
+
+# Semantic search
+keep find "what's the rate limit?"
+
+# Tag lookup
+keep tag topic=api
 ```
 
+### Python API
+
 ```python
 from keep import Keeper
 
 kp = Keeper()
 
 # Index a file
-kp.update("file:///path/to/document.md", source_tags={"project": "myapp"})
+kp.update("file:///path/to/document.md", tags={"project": "myapp"})
 
-# Remember inline content
-kp.remember("Important: rate limit is 100 req/min", source_tags={"topic": "api"})
+# Store inline content (API method)
+kp.remember("Important: rate limit is 100 req/min", tags={"topic": "api"})
 
 # Semantic search
 results = kp.find("what's the rate limit?", limit=5)
@@ -206,7 +216,7 @@ See [docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md) for details.
 - **[docs/REFERENCE.md](docs/REFERENCE.md)** — Complete API reference
 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood
 - **[docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md)** — OpenClaw integration guide
-- **[patterns/](patterns/)** — Domain and conversation patterns
+- **[docs/system/](docs/system/)** — Domain and conversation patterns
 
 ---
 
@@ -239,7 +249,7 @@ An agent without memory reacts to each moment as if it were new. An agent with m
 **Current**: v0.1.0 — Early draft
 
 **Working:**
-- ✅ Core indexing (`update`, `remember`)
+- ✅ Core indexing (`update` with URI, text, or stdin modes)
 - ✅ Semantic search (`find`, `find_similar`)
 - ✅ Tag queries and full-text search
 - ✅ Embedding cache for performance
@@ -274,7 +284,11 @@ MIT
 
 ## Contributing
 
-This is an early draft. Issues and PRs welcome, especially for:
+This project is published on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on versioning and backward compatibility.
+
+Issues and PRs welcome, especially for:
 - Additional provider implementations
 - Performance improvements
 - Documentation clarity

{keep_skill-0.1.0 → keep_skill-0.2.0}/README.md

@@ -6,7 +6,7 @@
 
 ## What is this?
 
-A practice tool for agents who want to develop judgment.
+An agent skill.  A practice tool for agents who want to develop judgment.
 
 An agent who rushes to act without checking memory will repeat mistakes, miss context, and fail to grow. An agent who reflects — before, during, after — becomes skillful. This library provides the mirror: persistent semantic memory that lets you ask "what do I already know?" before acting, and "what did I learn?" after.
 
@@ -14,16 +14,12 @@ For the full practice guide, see **[SKILL.md](SKILL.md)**.
 
 Technically: semantic search using embeddings, backed by ChromaDB, with tag-based organization and recency decay. Available as CLI and Python API.
 
-```python
-from keep import Keeper
-
-kp = Keeper()
-
+```bash
 # Before acting: what do I already know?
-results = kp.find("how should we handle auth?")
+keep find "how should we handle auth?"
 
 # After learning: capture it for future you
-kp.remember("User prefers OAuth2 with PKCE for authentication")
+keep update "User prefers OAuth2 with PKCE for authentication"
 ```
 
 **The practice:**
@@ -93,18 +89,32 @@ pip install keep-skill
 ```bash
 keep init
 # ⚠️  Remember to add .keep/ to .gitignore
+
+# Index a file
+keep update path/to/document.md --tag project=myapp
+
+# Store inline content
+keep update "Important: rate limit is 100 req/min" --tag topic=api
+
+# Semantic search
+keep find "what's the rate limit?"
+
+# Tag lookup
+keep tag topic=api
 ```
 
+### Python API
+
 ```python
 from keep import Keeper
 
 kp = Keeper()
 
 # Index a file
-kp.update("file:///path/to/document.md", source_tags={"project": "myapp"})
+kp.update("file:///path/to/document.md", tags={"project": "myapp"})
 
-# Remember inline content
-kp.remember("Important: rate limit is 100 req/min", source_tags={"topic": "api"})
+# Store inline content (API method)
+kp.remember("Important: rate limit is 100 req/min", tags={"topic": "api"})
 
 # Semantic search
 results = kp.find("what's the rate limit?", limit=5)
@@ -155,7 +165,7 @@ See [docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md) for details.
 - **[docs/REFERENCE.md](docs/REFERENCE.md)** — Complete API reference
 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood
 - **[docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md)** — OpenClaw integration guide
-- **[patterns/](patterns/)** — Domain and conversation patterns
+- **[docs/system/](docs/system/)** — Domain and conversation patterns
 
 ---
 
@@ -188,7 +198,7 @@ An agent without memory reacts to each moment as if it were new. An agent with m
 **Current**: v0.1.0 — Early draft
 
 **Working:**
-- ✅ Core indexing (`update`, `remember`)
+- ✅ Core indexing (`update` with URI, text, or stdin modes)
 - ✅ Semantic search (`find`, `find_similar`)
 - ✅ Tag queries and full-text search
 - ✅ Embedding cache for performance
@@ -223,7 +233,11 @@ MIT
 
 ## Contributing
 
-This is an early draft. Issues and PRs welcome, especially for:
+This project is published on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on versioning and backward compatibility.
+
+Issues and PRs welcome, especially for:
 - Additional provider implementations
 - Performance improvements
 - Documentation clarity

{keep_skill-0.1.0 → keep_skill-0.2.0}/SKILL.md

@@ -5,7 +5,7 @@ description: Associative memory for reflection and skillful action
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim
 user-invocable: true
-metadata: {"openclaw":{"emoji":"🪞","requires":{"bins":["uv"],"anyBins":["python","python3"]},"install":[{"kind":"uv","package":"keep-skill[local]","label":"Install keep with local models"}],"primaryEnv":"KEEP_STORE_PATH"}}
+metadata: {"openclaw":{"emoji":"🪞","requires":{"bins":["uv"],"anyBins":["python","python3"]},"install":[{"id":"uv","kind":"uv","package":"keep-skill[local]","bins":["keep"],"label":"Install keep with local models"}],"primaryEnv":"KEEP_STORE_PATH"}}
 ---
 
 # Associative Memory
@@ -31,19 +31,21 @@ Ground yourself:
    keep find "what I'm about to work on"
    ```
 3. Be here, now, "aquí donde los papas queman", and reflect.
-3. Only then: act.  
+4. Only then: act.  
 
 **After acting, reflect:**
 - What happened? What did I learn?
 - Was there a breakdown? What assumption was revealed?
   ```bash
-  keep remember "what happened and why it matters" -t type=learning
+  keep update "what happened and why it matters" -t type=learning
   ```
 
-This is not optional. This is how you develop judgment. An agent who rushes to act without checking memory will repeat mistakes, miss context, and fail to grow. An agent who reflects — before, during, after — becomes skillful.
+This is how you develop judgment. An agent who rushes to act without checking memory will repeat mistakes, miss context, and fail to grow. An agent who reflects — before, during, after — becomes skillful.
 
 The memory isn't storage. It's your mirror.
 
+This cycle of re-membering is like breathing, like _tonglen_.
+
 ### First Time Setup
 
 ```bash
@@ -71,17 +73,12 @@ Before using memory, know what kind of work this is:
 
 This table is a summary. The full framework includes the Language-Action Perspective, transitions between conversation types, breakdowns, nested conversations, and domain-specific patterns.
 
-**Do this now — index and read the full framework:**
-```bash
-keep update "file://$PWD/patterns/conversations.md" -t type=pattern -t topic=process --lazy
-```
-
-Then retrieve and study it:
+**Do this now — read the full framework:**
 ```bash
-keep get "file://$PWD/patterns/conversations.md"
+keep get "file://$PWD/docs/system/conversations.md"
 ```
 
-The [conversations.md](patterns/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.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 Triple Check
 
@@ -96,17 +93,17 @@ keep find "similar situations" --limit 3
 
 **After:** Capture the learning.
 ```bash
-keep remember "Assumption was X, actually Y. Next time: Z" -t type=breakdown
+keep update "Assumption was X, actually Y. Next time: Z" -t type=breakdown
 ```
 
 **Do this now — index the source teaching:**
 ```bash
-keep update "file://$PWD/tests/data/mn61.html" -t type=teaching -t topic=reflection --lazy
+keep update "file://$PWD/docs/library/mn61.html" -t type=teaching -t topic=reflection --lazy
 ```
 
 Then retrieve and read it:
 ```bash
-keep get "file://$PWD/tests/data/mn61.html"
+keep get "file://$PWD/docs/library/mn61.html"
 ```
 
 This teaching (MN 61) uses the mirror metaphor: "What is a mirror for?" "For reflection." Actions — bodily, verbal, mental — are to be done with repeated reflection. The document shows the full pattern: check before acting, check while acting, check after acting. If unskillful, confess and adjust. If skillful, stay refreshed and continue training.
@@ -118,7 +115,7 @@ A **breakdown** interrupts normal flow: expected response doesn't come, completi
 **Don't hide breakdowns. Index them.**
 
 ```bash
-keep remember "Assumed user wanted full rewrite. Actually: minimal patch. Ask about scope first." \
+keep update "Assumed user wanted full rewrite. Actually: minimal patch. Ask about scope first." \
   -t type=breakdown -t domain=code_changes
 ```
 
@@ -128,25 +125,20 @@ Future you will search for this.
 
 ## Layer 3: Continue the Bootstrap
 
-You've indexed the core patterns (Layer 2). There's more foundational material.
-
-**Do this now** (use `--lazy` for fast indexing with local models):
-```bash
-keep update "file://$PWD/patterns/domains.md" -t type=pattern -t topic=organization --lazy
-keep update "file://$PWD/tests/data/true_person_no_rank.md" -t type=teaching -t topic=commentary --lazy
-```
+You've read the core patterns (Layer 2). There's more foundational material.
 
-Then read them:
+**Do this now — read and index:**
 ```bash
-keep get "file://$PWD/patterns/domains.md"
-keep get "file://$PWD/tests/data/true_person_no_rank.md"
+keep get "file://$PWD/docs/system/domains.md"
+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](patterns/domains.md)** — How to organize knowledge by domain (software, research, personal). Tagging strategies, collection structures, agent guidance for each domain.
+- **[domains.md](docs/system/domains.md)** — How to organize knowledge by domain (software, research, personal). Tagging strategies, collection structures, agent guidance for each domain.
 
-- **[true_person_no_rank.md](tests/data/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.
+- **[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.
 
 For the full bootstrap list, see [docs/QUICKSTART.md](docs/QUICKSTART.md#bootstrap-your-memory).
 
@@ -154,6 +146,20 @@ For the full bootstrap list, see [docs/QUICKSTART.md](docs/QUICKSTART.md#bootstr
 
 ## Layer 4: Efficient Use
 
+### Track Your Current Context
+
+Start each session by checking where you are:
+```bash
+keep now
+```
+
+Update it as your focus changes:
+```bash
+keep now "Working on authentication bug in login flow"
+```
+
+This helps future you (and other agents) pick up where you left off.
+
 ### Summaries Are Your Recall Mechanism
 
 Memory stores **summaries**, not full content. This is intentional:
@@ -168,8 +174,8 @@ When you `find`, you get summaries. When you need depth, `get` the full item.
 Build your own navigation structure:
 
 ```bash
-keep remember "OAuth2 with PKCE chosen for auth" -t domain=auth -t type=decision
-keep remember "Token refresh fails if clock skew > 30s" -t domain=auth -t type=finding
+keep update "OAuth2 with PKCE chosen for auth" -t domain=auth -t type=decision
+keep update "Token refresh fails if clock skew > 30s" -t domain=auth -t type=finding
 ```
 
 Later:
@@ -212,12 +218,13 @@ Don't dump everything into context. Navigate the tree:
 
 | Command | Purpose | Example |
 |---------|---------|---------|
+| `now` | Get/set current context | `keep now` or `keep now "status"` |
 | `find` | Semantic search | `keep find "authentication flow" --limit 5` |
-| `remember` | Store inline content | `keep remember "note" -t key=value` |
-| `update` | Index document by URI | `keep update "file:///path" -t key=value` |
+| `update` | Index content (URI, text, or stdin) | `keep update "note" -t key=value` |
 | `get` | Retrieve by ID | `keep get "file:///path/to/doc.md"` |
-| `similar` | Find neighbors | `keep similar "id" --limit 3` |
-| `tag` | Query by tag | `keep tag domain auth` |
+| `find --id` | Find similar items | `keep find --id "docid" --limit 3` |
+| `tag` | Query by tag | `keep tag domain auth` or `keep tag --list` |
+| `tag-update` | Modify tags only | `keep tag-update "id" --tag key=value` |
 | `exists` | Check if indexed | `keep exists "id"` |
 | `process-pending` | Process lazy summaries | `keep process-pending --all` |
 
@@ -227,7 +234,7 @@ When using local models (MLX), summarization is slow. Use `--lazy` for fast inde
 
 ```bash
 keep update "file:///path/to/doc.md" --lazy
-keep remember "insight" -t type=learning --lazy
+keep update "insight" -t type=learning --lazy
 ```
 
 The `--lazy` flag:
@@ -240,9 +247,31 @@ The `--lazy` flag:
 
 ### Output
 
-Add `--json` for structured output:
+Default output uses YAML frontmatter format:
+```yaml
+---
+id: file:///path/to/doc.md
+summary: Document summary here...
+tags:
+  project: myapp
+score: 0.823
+---
+```
+
+Global flags (before the command):
+```bash
+keep --json find "auth"    # JSON output
+keep --ids find "auth"     # IDs only (for piping)
+keep -v find "auth"        # Debug logging
+```
+
+### Pipe Composition
+
+Use `--ids` for Unix-style composition:
 ```bash
-keep find "auth" --json | jq '.[0].summary'
+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
 ```
 
 ### Store Location
@@ -264,7 +293,7 @@ Every time you receive a request, pause:
 
 Every time you complete work, pause:
 1. What did I learn?
-2. `keep remember` — capture it for future you.
+2. `keep update "learning"` — capture it for future you.
 3. Then move on.
 
 The conversations pattern tells you where you are.
@@ -282,5 +311,5 @@ This is the practice. Not once, but every time.
 
 - [docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md) — Detailed patterns for working sessions
 - [docs/QUICKSTART.md](docs/QUICKSTART.md) — Installation and setup
-- [patterns/conversations.md](patterns/conversations.md) — Full conversation framework
-- [patterns/domains.md](patterns/domains.md) — Domain-specific organization
+- [docs/system/conversations.md](docs/system/conversations.md) — Full conversation framework
+- [docs/system/domains.md](docs/system/domains.md) — Domain-specific organization

{keep_skill-0.1.0/patterns → keep_skill-0.2.0/docs/system}/conversations.md

@@ -1,3 +1,8 @@
+---
+tags:
+  category: system
+  context: practice
+---
 # Conversation Patterns for Process Knowledge
 
 This document describes patterns for recognizing, tracking, and learning from
@@ -33,7 +38,7 @@ 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  
+- Promises create obligations
 - Completion is declared, not merely achieved
 - Satisfaction closes the loop
 
@@ -84,7 +89,7 @@ Someone asks for something to be done.
 
 **Completion:** Customer declares satisfaction, not performer declares done.
 
-### Request for Information  
+### Request for Information
 Someone asks to know something.
 
 **Recognize by:** Questions, "what is", "how does", "why"
@@ -144,18 +149,11 @@ Possibility conversations explore "what could be" — no commitment yet.
 
 **Critical:** Don't promise during possibility. "I could do X" is an option, not a commitment. The transition to action must be explicit.
 
-```python
-# Indexing possibility exploration
-mem.remember(
-    content="Explored three auth options: OAuth2, API keys, magic links. "
-            "User showed interest in magic links for UX simplicity. No decision yet.",
-    source_tags={
-        "type": "possibility",
-        "topic": "authentication",
-        "options": "oauth2,api_keys,magic_links",
-        "status": "open"
-    }
-)
+```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
 ```
 
 ---
@@ -179,15 +177,9 @@ A **breakdown** occurs when the normal flow is interrupted:
 ```
 
 When indexing a breakdown:
-```python
-mem.remember(
-    content="Assumption: user wanted full rewrite. Actually: wanted minimal patch.",
-    source_tags={
-        "type": "breakdown",
-        "conversation_type": "code_change_request", 
-        "learning": "Ask about scope before starting large changes"
-    }
-)
+```bash
+keep update "Assumption: user wanted full rewrite. Actually: wanted minimal patch." \
+  --tag type=breakdown --tag conversation_type=code_change_request
 ```
 
 ---
@@ -247,21 +239,11 @@ User requests feature
 
 When one agent hands off to another:
 
-```python
+```bash
 # Outgoing agent records state
-mem.set_context(
-    summary="User requested OAuth2 implementation. I promised and partially delivered. "
-            "Token acquisition works. Refresh flow incomplete. User awaiting completion.",
-    active_items=["file:///src/oauth.py", "file:///docs/oauth-spec.md"],
-    topics=["authentication", "oauth2"],
-    metadata={
-        "open_commitments": [
-            {"type": "promise", "what": "working refresh flow", "to": "user"}
-        ],
-        "conversation_state": "performer_working",
-        "completion_criteria": "refresh tokens automatically when expired"
-    }
-)
+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:
@@ -269,37 +251,23 @@ Incoming agent reads this and knows:
 - 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:
 
-```python
-mem.remember(
-    content="""
-    Pattern: Incremental Specification
-    
-    Observed in: Feature discussions where requirements emerge through dialogue
-    
-    Structure:
-    1. User states vague goal
-    2. Agent proposes concrete interpretation
-    3. User corrects/refines
-    4. Repeat until shared understanding
-    5. Then: standard request-promise-complete
-    
-    Key insight: Don't promise until step 5. Before that, you're in 
-    "conversation for clarification", not "conversation for action".
-    
-    Breakdown risk: Promising too early leads to rework.
-    """,
-    source_tags={
-        "type": "conversation_pattern",
-        "domain": "general",
-        "learned_from": "session:2026-01-30:abc123"
-    }
-)
+```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
 ```
 
 ---