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

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

@@ -61,3 +61,5 @@ coverage.xml
 .keep/
 test_extraction_store/
 .DS_Store
+.claude/
+.agents/

keep_skill-0.4.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: keep-skill
+Version: 0.4.1
+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
+Author: Hugh Pyle
+License: MIT
+License-File: LICENSE
+Keywords: agents,chromadb,embeddings,semantic-memory,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Requires-Python: <3.14,>=3.11
+Requires-Dist: chromadb>=0.4
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.9
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: documents
+Requires-Dist: beautifulsoup4>=4.9; extra == 'documents'
+Requires-Dist: pypdf>=5.0; extra == 'documents'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: local
+Requires-Dist: beautifulsoup4>=4.9; extra == 'local'
+Requires-Dist: mlx-lm>=0.10; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'local'
+Requires-Dist: mlx>=0.10; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'local'
+Requires-Dist: pypdf>=5.0; extra == 'local'
+Requires-Dist: sentence-transformers>=2.2; extra == 'local'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.10; extra == 'mlx'
+Requires-Dist: mlx>=0.10; extra == 'mlx'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: openclaw
+Requires-Dist: anthropic>=0.18.0; extra == 'openclaw'
+Requires-Dist: google-genai>=1.0.0; extra == 'openclaw'
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2; extra == 'sentence-transformers'
+Description-Content-Type: text/markdown
+
+# keep
+
+**Semantic memory with version history.**
+
+Index documents and notes. Search by meaning. Track changes over time.
+
+```bash
+pip install 'keep-skill[local]'
+keep init
+
+# Index content
+keep update path/to/document.md -t project=myapp
+keep update "Rate limit is 100 req/min" -t topic=api
+
+# Search by meaning
+keep find "what's the rate limit?"
+
+# Track what you're working on
+keep now "Debugging auth flow"
+keep now -V 1                    # Previous context
+```
+
+---
+
+## What It Does
+
+- **Semantic search** — Find by meaning, not just keywords
+- **Version history** — All documents retain history on update
+- **Tag organization** — Filter and navigate with key=value tags
+- **Recency decay** — Recent items rank higher in search
+- **Works offline** — Local embedding models by default
+
+Backed by ChromaDB for vectors, SQLite for metadata and versions.
+
+---
+
+## Installation
+
+**Python 3.11–3.13 required.**
+
+```bash
+# Recommended: local models (works offline)
+pip install 'keep-skill[local]'
+
+# Or with uv (faster):
+uv tool install 'keep-skill[local]'
+
+# API-based alternative (requires OPENAI_API_KEY)
+pip install 'keep-skill[openai]'
+```
+
+First run downloads embedding models (~3-5 minutes).
+
+---
+
+## Quick Start
+
+```bash
+keep init                              # Creates .keep/ at repo root
+
+# Index files and notes
+keep update file:///path/to/doc.md -t project=myapp
+keep update "Important insight" -t type=note
+
+# Search
+keep find "authentication flow" --limit 5
+keep find "auth" --since P7D           # Last 7 days
+
+# Retrieve
+keep get file:///path/to/doc.md
+keep get ID -V 1                       # Previous version
+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
+
+# Current context
+keep now                               # Show what you're working on
+keep now "Fixing login bug"            # Update context
+```
+
+### Python API
+
+```python
+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"})
+
+# Search
+results = kp.find("rate limit", limit=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.summary}")
+
+# Version history
+prev = kp.get_version("doc:1", offset=1)
+versions = kp.list_versions("doc:1")
+```
+
+See [docs/QUICKSTART.md](docs/QUICKSTART.md) for configuration and more examples.
+
+---
+
+## Documentation
+
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Setup, configuration, lazy summarization
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Complete CLI and API reference
+- **[docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md)** — Working session patterns
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood
+- **[SKILL.md](SKILL.md)** — The reflective practice (for AI agents)
+
+---
+
+## For AI Agents
+
+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
+
+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
+
+---
+
+## Contributing
+
+Published on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).
+
+Issues and PRs welcome:
+- Provider implementations
+- Performance improvements
+- Documentation clarity
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

keep_skill-0.4.1/README.md

@@ -0,0 +1,168 @@
+# keep
+
+**Semantic memory with version history.**
+
+Index documents and notes. Search by meaning. Track changes over time.
+
+```bash
+pip install 'keep-skill[local]'
+keep init
+
+# Index content
+keep update path/to/document.md -t project=myapp
+keep update "Rate limit is 100 req/min" -t topic=api
+
+# Search by meaning
+keep find "what's the rate limit?"
+
+# Track what you're working on
+keep now "Debugging auth flow"
+keep now -V 1                    # Previous context
+```
+
+---
+
+## What It Does
+
+- **Semantic search** — Find by meaning, not just keywords
+- **Version history** — All documents retain history on update
+- **Tag organization** — Filter and navigate with key=value tags
+- **Recency decay** — Recent items rank higher in search
+- **Works offline** — Local embedding models by default
+
+Backed by ChromaDB for vectors, SQLite for metadata and versions.
+
+---
+
+## Installation
+
+**Python 3.11–3.13 required.**
+
+```bash
+# Recommended: local models (works offline)
+pip install 'keep-skill[local]'
+
+# Or with uv (faster):
+uv tool install 'keep-skill[local]'
+
+# API-based alternative (requires OPENAI_API_KEY)
+pip install 'keep-skill[openai]'
+```
+
+First run downloads embedding models (~3-5 minutes).
+
+---
+
+## Quick Start
+
+```bash
+keep init                              # Creates .keep/ at repo root
+
+# Index files and notes
+keep update file:///path/to/doc.md -t project=myapp
+keep update "Important insight" -t type=note
+
+# Search
+keep find "authentication flow" --limit 5
+keep find "auth" --since P7D           # Last 7 days
+
+# Retrieve
+keep get file:///path/to/doc.md
+keep get ID -V 1                       # Previous version
+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
+
+# Current context
+keep now                               # Show what you're working on
+keep now "Fixing login bug"            # Update context
+```
+
+### Python API
+
+```python
+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"})
+
+# Search
+results = kp.find("rate limit", limit=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.summary}")
+
+# Version history
+prev = kp.get_version("doc:1", offset=1)
+versions = kp.list_versions("doc:1")
+```
+
+See [docs/QUICKSTART.md](docs/QUICKSTART.md) for configuration and more examples.
+
+---
+
+## Documentation
+
+- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Setup, configuration, lazy summarization
+- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Complete CLI and API reference
+- **[docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md)** — Working session patterns
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — How it works under the hood
+- **[SKILL.md](SKILL.md)** — The reflective practice (for AI agents)
+
+---
+
+## For AI Agents
+
+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
+
+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
+
+---
+
+## Contributing
+
+Published on [PyPI as `keep-skill`](https://pypi.org/project/keep-skill/).
+
+Issues and PRs welcome:
+- Provider implementations
+- Performance improvements
+- Documentation clarity
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

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

@@ -1,6 +1,6 @@
 ---
 name: keep
-version: 0.1.0
+version: 0.4.1
 description: Associative memory for reflection and skillful action
 homepage: https://github.com/hughpyle/keep
 runtime: python:3.12-slim
@@ -26,12 +26,16 @@ You have a memory. Use it — not sometimes, but as practice.
 
 Ground yourself:
 1. What kind of conversation is this? (Action? Possibility? Clarification?)
-2. What do I already know about this?
+2. Where am I? What's the current context?
+   ```bash
+   keep now
+   ```
+3. What do I already know about this?
    ```bash
    keep find "what I'm about to work on"
    ```
-3. Be here, now, "aquí donde los papas queman", and reflect.
-4. Only then: act.  
+4. Be here, now, "aquí donde los papas queman", and reflect.
+5. Only then: act.  
 
 **After acting, reflect:**
 - What happened? What did I learn?
@@ -106,7 +110,7 @@ Then retrieve and read it:
 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.
+This teaching ([MN 61](docs/library/mn61.html)) 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.
 
 ### Breakdowns Are Valuable
 
@@ -140,7 +144,7 @@ These aren't test fixtures. They're seed wisdom:
 
 - **[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).
+The [docs/library/](docs/library/) directory contains additional seed material.
 
 ---
 
@@ -158,8 +162,41 @@ Update it as your focus changes:
 keep now "Working on authentication bug in login flow"
 ```
 
+Check previous context if needed:
+```bash
+keep now -V 1          # Previous context
+keep now --history     # All versions
+```
+
 This helps future you (and other agents) pick up where you left off.
 
+### Similar Items for Discovery
+
+When you retrieve an item, you automatically see related items:
+
+```bash
+keep get ID                  # Shows up to 3 similar items
+keep get ID --similar        # List more similar items
+keep get ID --no-similar     # Just the document
+```
+
+This enables serendipitous discovery — you may find relevant context you didn't know to search for.
+
+### Version History
+
+All documents retain history on update. Use this to see how understanding evolved:
+
+```bash
+keep get ID -V 1       # Previous version
+keep get ID --history  # List all versions (default 10, -n to override)
+```
+
+Text updates use content-addressed IDs — same content = same ID. This enables versioning through tag changes:
+```bash
+keep update "auth decision" -t status=draft    # Creates ID from content
+keep update "auth decision" -t status=final    # Same ID, new version
+```
+
 ### Summaries Are Your Recall Mechanism
 
 Memory stores **summaries**, not full content. This is intentional:
@@ -180,8 +217,8 @@ keep update "Token refresh fails if clock skew > 30s" -t domain=auth -t type=fin
 
 Later:
 ```bash
-keep tag domain auth     # Everything about auth
-keep tag type decision   # All decisions made
+keep tag domain=auth     # Everything about auth
+keep tag type=decision   # All decisions made
 ```
 
 **Suggested tag dimensions:**
@@ -219,13 +256,20 @@ 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` |
+| `now -V N` | Previous context versions | `keep now -V 1` or `keep now --history` |
+| `find` | Semantic similarity search | `keep find "authentication flow" --limit 5` |
+| `find --id` | Find similar to existing item | `keep find --id "docid" --limit 3` |
+| `search` | Full-text search in summaries | `keep search "OAuth"` |
+| `list` | List recent item IDs | `keep list` or `keep --full list` |
 | `update` | Index content (URI, text, or stdin) | `keep update "note" -t key=value` |
-| `get` | Retrieve by ID | `keep get "file:///path/to/doc.md"` |
-| `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"` |
+| `get` | Retrieve item (shows similar items) | `keep get "file:///path/to/doc.md"` |
+| `get --similar` | List similar items | `keep get ID --similar` or `-n 20` for more |
+| `get -V N` | Previous versions | `keep get ID -V 1` or `keep get ID --history` |
+| `tag` | List tag values or find by tag | `keep tag domain=auth` or `keep tag --list` |
+| `tag-update` | Modify tags on existing item | `keep tag-update "id" --tag key=value` |
+| `collections` | List all collections | `keep collections` |
+| `init` | Initialize or verify store | `keep init` |
+| `config` | Show configuration and store path | `keep config` |
 | `process-pending` | Process lazy summaries | `keep process-pending --all` |
 
 ### Fast Indexing with `--lazy`
@@ -251,17 +295,22 @@ Default output uses YAML frontmatter format:
 ```yaml
 ---
 id: file:///path/to/doc.md
-summary: Document summary here...
-tags:
-  project: myapp
+tags: {project: myapp, domain: auth}
+similar:
+  - doc:related-auth (0.89)
+  - doc:token-notes (0.85)
 score: 0.823
+prev:
+  - v1: 2026-01-15 Previous summary...
 ---
+Document summary here...
 ```
 
 Global flags (before the command):
 ```bash
 keep --json find "auth"    # JSON output
 keep --ids find "auth"     # IDs only (for piping)
+keep --full list           # Full items (overrides IDs-only default)
 keep -v find "auth"        # Debug logging
 ```
 
@@ -310,6 +359,7 @@ This is the practice. Not once, but every time.
 ## See Also
 
 - [docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md) — Detailed patterns for working sessions
+- [docs/REFERENCE.md](docs/REFERENCE.md) — Complete CLI and API reference
 - [docs/QUICKSTART.md](docs/QUICKSTART.md) — Installation and setup
 - [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.2.0 → keep_skill-0.4.1}/keep/__init__.py

@@ -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
 
-__version__ = "0.2.0"
+__version__ = "0.4.1"
 __all__ = [
     "Keeper",
     "Item",