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

keep_skill-0.4.1.dist-info/METADATA

@@ -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.2.0.dist-info → keep_skill-0.4.1.dist-info}/RECORD

@@ -1,28 +1,28 @@
-keep/__init__.py,sha256=371SMehsuIYYX8AfbaPplhF-YJa8qcpoUyGTOcX9Iwg,1581
+keep/__init__.py,sha256=1WVkySoomQuf9-o3pIKs1CC2OwIyfkiaCxn-mO6nhd8,1581
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=xM0VPzSNdeXp94fbuEzq1K1L7EZ_Ojy3U1UOMhQrgXo,48158
+keep/api.py,sha256=EaPkI9Gv1r5LM8ZibqquGP_59xf4kQlCdv7nfct8QZw,58894
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=Gl_0Ap5FWWPD7Hwj3FoGEgN3e0yyW8YeIVx75gk1KzY,25209
-keep/config.py,sha256=wRTKcvpQdZQQl7vAr5RKgIbSjkgYpPc_w78qmXdmtmU,15833
+keep/cli.py,sha256=3flcfZHjvnHY8TxT-HJBBAuKnDusPAUD3ZwuMYYU7sw,40470
+keep/config.py,sha256=RRnHHvhc9KkJBYt0rpAFIvAVXw40b56xtT74TFIBiDU,15832
 keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
-keep/document_store.py,sha256=1WhlF6hpshVXp2MGGF-zBJi6pSmS-tMHFmwG3EwaXik,17515
+keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
 keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
 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=KRQ2AGQNnKlDBoVbOF7tkSv1oTmlimWtJzxQ3YcaVKY,5472
-keep/store.py,sha256=txaydUIrhbB-S-cSlSszxOVlAg0kJXmS_Mnit6jzR3c,14483
+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/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
-keep/providers/embedding_cache.py,sha256=hUuQuP8MeXQdEr0eYqHesH-5wX1kRpumJQQ3o1_DI_A,8601
+keep/providers/embedding_cache.py,sha256=gna6PZEJanbn2GUN0vj1b1MC0xVWePM9cot2KgZUdu8,8856
 keep/providers/embeddings.py,sha256=zi8GyitKexdbCJyU1nLrUhGt_zzPn3udYrrPZ5Ak8Wo,9081
 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.2.0.dist-info/METADATA,sha256=mQtDWzLbEX_L6aKoM807zxph0y4J6IP45zGXQIvHuFU,9305
-keep_skill-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-keep_skill-0.2.0.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
-keep_skill-0.2.0.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
-keep_skill-0.2.0.dist-info/RECORD,,
+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.2.0.dist-info/METADATA

@@ -1,304 +0,0 @@
-Metadata-Version: 2.4
-Name: keep-skill
-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
-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
-
-**Associative memory for reflection and skillful action.**
-
----
-
-## What is this?
-
-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.
-
-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.
-
-```bash
-# Before acting: what do I already know?
-keep find "how should we handle auth?"
-
-# After learning: capture it for future you
-keep update "User prefers OAuth2 with PKCE for authentication"
-```
-
-**The practice:**
-- Pause before acting — check what you already know
-- Notice breakdowns — when assumptions surface, that's valuable
-- Reflect after — capture learnings so future you can find them
-
-**The technology:**
-- Semantic search (by meaning, not keywords)
-- Persistent across sessions (ChromaDB)
-- Tag-based organization and filtering
-- Recency decay (recent items rank higher)
-- Provider abstraction (local models or APIs)
-- CLI and Python API
-
----
-
-## Quick Start
-
-### Requirements
-
-- **Python:** 3.11, 3.12, or 3.13 (3.14+ not yet supported due to dependency constraints)
-- **Installation time:** 3-5 minutes (ChromaDB dependency resolution + embedding model downloads)
-
-### Installation
-
-#### For users (just want the `keep` command)
-
-```bash
-# With pip:
-pip install 'keep-skill[local]'
-
-# Or with uv (faster, auto-manages isolated environment):
-# Install uv first: https://docs.astral.sh/uv/getting-started/installation/
-uv tool install 'keep-skill[local]'
-```
-
-#### For developers (working on keep itself)
-
-```bash
-git clone https://github.com/hughpyle/keep
-cd keep
-
-# Create and activate a virtual environment
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-# Install in editable mode with local models
-pip install -e '.[local,dev]'
-
-# Or with uv (faster):
-uv pip install -e '.[local,dev]'
-```
-
-#### Optional extras
-
-```bash
-# OpenClaw integration (uses your configured models):
-pip install 'keep-skill[openclaw]'
-
-# Minimal install (configure providers manually):
-pip install keep-skill
-```
-
-**After installation:**
-
-```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", tags={"project": "myapp"})
-
-# 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)
-for r in results:
-    print(f"[{r.score:.2f}] {r.summary}")
-
-# Tag lookup
-api_docs = kp.query_tag("topic", "api")
-```
-
-See [docs/QUICKSTART.md](docs/QUICKSTART.md) for more examples.
-
----
-
-## OpenClaw Integration
-
-If you have [OpenClaw](https://openclaw.dev) configured, keep automatically uses your configured models:
-
-```bash
-# Install with OpenClaw support
-pip install 'keep-skill[openclaw]'
-
-# Set your Anthropic API key (if using Claude models)
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Initialize (auto-detects ~/.openclaw/openclaw.json)
-keep init
-# ✓ Detected providers:
-#   Embedding: sentence-transformers (local)
-#   Summarization: anthropic (claude-sonnet-4)
-```
-
-**Benefits:**
-- 🔄 Unified model configuration (DRY principle)
-- 🧠 Best of both: local embeddings + smart summarization
-- 🔒 Privacy-preserving (embeddings stay local)
-- 💰 Cost-effective (~$0.0001/document)
-
-See [docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md) for details.
-
----
-
-## Documentation
-
-- **[SKILL.md](SKILL.md)** — The practice guide (start here for how to use memory skillfully)
-- **[docs/QUICKSTART.md](docs/QUICKSTART.md)** — Installation, setup, configuration
-- **[docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md)** — Detailed agent patterns, Python API
-- **[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
-- **[docs/system/](docs/system/)** — Domain and conversation patterns
-
----
-
-## Philosophy
-
-### Practice
-
-Memory isn't storage — it's a mirror for reflection.
-
-The triple check: before acting (what do I know?), during (notice breakdowns), after (capture learning). Breakdowns are valuable — they reveal assumptions. Index them, don't hide them.
-
-An agent without memory reacts to each moment as if it were new. An agent with memory reflects, learns, and grows. See **[SKILL.md](SKILL.md)** for the full practice guide.
-
-### Technical Design
-
-**Schema as Data** — Configuration stored as queryable documents, not hardcoded.
-
-**Semantic by Default** — Search by meaning via vector similarity, not keywords.
-
-**Lazy Loading** — Dependencies loaded only when needed; missing providers give helpful errors.
-
-**Provider Agnostic** — Pluggable backends for embeddings, summarization, and storage.
-
-**No Original Content** — Only summaries and embeddings stored. URIs can be re-fetched if needed.
-
----
-
-## Status
-
-**Current**: v0.1.0 — Early draft
-
-**Working:**
-- ✅ Core indexing (`update` with URI, text, or stdin modes)
-- ✅ Semantic search (`find`, `find_similar`)
-- ✅ Tag queries and full-text search
-- ✅ Embedding cache for performance
-- ✅ Recency decay (ACT-R style)
-- ✅ CLI interface
-- ✅ Provider abstraction with lazy loading
-
-**Planned** (see [later/](later/)):
-- ⏳ Context management (working context, top-of-mind retrieval)
-- ⏳ Private/shared routing
-- ⏳ Relationship graphs between items
-- ⏳ LLM-based tagging
-
----
-
-## Requirements
-
-- Python 3.11+
-- ChromaDB (vector store)
-- One embedding provider:
-  - sentence-transformers (local, default)
-  - MLX (Apple Silicon, local)
-  - OpenAI (API, requires key)
-
----
-
-## License
-
-MIT
-
----
-
-## Contributing
-
-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
-- OpenClaw integration patterns
-
----
-
-## Related Projects
-
-- [ChromaDB](https://github.com/chroma-core/chroma) — Vector database backend
-- [sentence-transformers](https://github.com/UKPLab/sentence-transformers) — Embedding models
-- [MLX](https://github.com/ml-explore/mlx) — Apple Silicon ML framework
-- [OpenClaw](https://openclaw.dev) — Agent framework (integration target)