keep-skill 0.4.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

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
+
+This is top-of-mind right 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 focus: ..."`

keep/store.py

@@ -58,15 +58,9 @@ class ChromaStore:
             embedding_dimension: Expected dimension of embeddings (for validation).
                 Can be None for read-only access; will be set on first write.
         """
-        try:
-            import chromadb
-            from chromadb.config import Settings
-        except ImportError:
-            raise RuntimeError(
-                "ChromaStore requires 'chromadb' library. "
-                "Install with: pip install chromadb"
-            )
-        
+        import chromadb
+        from chromadb.config import Settings
+
         self._store_path = store_path
         self._embedding_dimension = embedding_dimension
         

keep/types.py

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

{keep_skill-0.4.1.dist-info → keep_skill-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.4.1
+Version: 0.6.0
 Summary: Semantic memory - remember and search documents by meaning
 Project-URL: Homepage, https://github.com/hughpyle/keep
 Project-URL: Repository, https://github.com/hughpyle/keep
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
 Index documents and notes. Search by meaning. Track changes over time.
 
 ```bash
-pip install 'keep-skill[local]'
+uv tool install 'keep-skill[local]'
 keep init
 
 # Index content
@@ -90,16 +90,20 @@ Backed by ChromaDB for vectors, SQLite for metadata and versions.
 **Python 3.11–3.13 required.**
 
 ```bash
-# Recommended: local models (works offline)
-pip install 'keep-skill[local]'
-
-# Or with uv (faster):
+# Recommended: uv (isolated environment, fast)
 uv tool install 'keep-skill[local]'
 
-# API-based alternative (requires OPENAI_API_KEY)
-pip install 'keep-skill[openai]'
+# Alternative: pip in a virtual environment
+python -m venv .venv && source .venv/bin/activate
+pip install 'keep-skill[local]'
+
+# API-based (requires OPENAI_API_KEY)
+uv tool install 'keep-skill[openai]'
 ```
 
+> **Note:** Always use an isolated environment (uv or venv). Installing with system pip
+> may cause version conflicts with dependencies like typer.
+
 First run downloads embedding models (~3-5 minutes).
 
 ---

{keep_skill-0.4.1.dist-info → keep_skill-0.6.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
-keep/__init__.py,sha256=1WVkySoomQuf9-o3pIKs1CC2OwIyfkiaCxn-mO6nhd8,1581
+keep/__init__.py,sha256=lAm_iUUxz76EanZYE5UviCD1p2OSQwUag4Q67EP4oKE,1617
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=EaPkI9Gv1r5LM8ZibqquGP_59xf4kQlCdv7nfct8QZw,58894
+keep/api.py,sha256=Ja_9zKr0bDL2UyBDZ03HrQHYkI9mdOMxuQlstyxJzmo,64477
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=3flcfZHjvnHY8TxT-HJBBAuKnDusPAUD3ZwuMYYU7sw,40470
-keep/config.py,sha256=RRnHHvhc9KkJBYt0rpAFIvAVXw40b56xtT74TFIBiDU,15832
+keep/cli.py,sha256=P7oKtv3TFL5BZNEfwh6kAFuqoeeqFxfVYssjdg0RMLc,44761
+keep/config.py,sha256=gw_QMY0VkCVF6xi-B9zGvZSza4z2QtiJucqgZJF3Xqg,16227
 keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
 keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
 keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
@@ -11,8 +11,13 @@ keep/indexing.py,sha256=dpPYo3WXnIhFDWinz5ZBZVk7_qumeNpP4EpOIY0zMbs,6063
 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=d_exdEBQM7agpJcXL-nGsl46zXPQ2t35C8QF-NQX_Bw,18097
-keep/types.py,sha256=f6uOSYsYt6mj1ulKn2iRkooi__dWCiOQFPD6he2eID4,2149
+keep/store.py,sha256=SBc2QdTyApdDDVjm2uZQI6tGbV5Hurfetgj7dyTO65o,17881
+keep/types.py,sha256=_ytiG1O-9fY39o_TOktzYaFxHZBcIfuYgGI_vKsEx30,2316
+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/providers/base.py,sha256=7Ug4Kj9fK2Dq4zDcZjn-GKsoZBOAlB9b-FMk969ER-g,14590
 keep/providers/documents.py,sha256=EXeSy5i3RUL0kciIC6w3ldAEfbTIyC5fgfzC_WAI0iY,8211
@@ -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.1.dist-info/METADATA,sha256=sasoFYgfL9FK4nuIK99pruVoiUH65I-SN30giqc2wHs,6387
-keep_skill-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-keep_skill-0.4.1.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
-keep_skill-0.4.1.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
-keep_skill-0.4.1.dist-info/RECORD,,
+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,,