keep-skill 0.1.0__tar.gz

keep_skill-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Project specific
+.keep/
+test_extraction_store/

keep_skill-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugh Pyle, inguz ᛜ outcomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keep_skill-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: keep-skill
+Version: 0.1.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?
+
+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.
+
+```python
+from keep import Keeper
+
+kp = Keeper()
+
+# Before acting: what do I already know?
+results = kp.find("how should we handle auth?")
+
+# After learning: capture it for future you
+kp.remember("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
+```
+
+```python
+from keep import Keeper
+
+kp = Keeper()
+
+# Index a file
+kp.update("file:///path/to/document.md", source_tags={"project": "myapp"})
+
+# Remember inline content
+kp.remember("Important: rate limit is 100 req/min", source_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
+- **[patterns/](patterns/)** — 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`, `remember`)
+- ✅ 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 is an early draft. 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)

keep_skill-0.1.0/README.md

@@ -0,0 +1,239 @@
+# keep
+
+**Associative memory for reflection and skillful action.**
+
+---
+
+## What is this?
+
+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.
+
+```python
+from keep import Keeper
+
+kp = Keeper()
+
+# Before acting: what do I already know?
+results = kp.find("how should we handle auth?")
+
+# After learning: capture it for future you
+kp.remember("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
+```
+
+```python
+from keep import Keeper
+
+kp = Keeper()
+
+# Index a file
+kp.update("file:///path/to/document.md", source_tags={"project": "myapp"})
+
+# Remember inline content
+kp.remember("Important: rate limit is 100 req/min", source_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
+- **[patterns/](patterns/)** — 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`, `remember`)
+- ✅ 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 is an early draft. 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)