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

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

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

keep_skill-0.3.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: keep-skill
+Version: 0.3.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
+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 --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.3.0/README.md

@@ -0,0 +1,167 @@
+# 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 --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.