Metadata-Version: 2.4
Name: keep-skill
Version: 0.22.0
Summary: Reflective 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: anthropic>=0.40.0
Requires-Dist: chromadb>=0.4
Requires-Dist: google-genai>=1.0.0
Requires-Dist: openai>=1.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.9
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: 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'
Description-Content-Type: text/markdown

# keep

An agent-skill for self-reflection and learning. It includes [skill instructions](SKILL.md) for reflective practice, and a semantic memory system with a command-line interface.

```bash
pip install keep-skill
export VOYAGE_API_KEY=...        # Or OPENAI_API_KEY, GEMINI_API_KEY

# Index content (store auto-initializes on first use)
keep put https://inguz.substack.com/p/keep -t topic=practice
keep put "file://$(keep config tool)/docs/library/impermanence_verse.txt" -t type=teaching
keep put "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 intentions
```

---

## 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
pip install keep-skill
```

API SDKs for Voyage, OpenAI, Anthropic, and Gemini are included. Set an API key:

```bash
export VOYAGE_API_KEY=...      # Recommended (Anthropic's partner)
# Or: export OPENAI_API_KEY=... or GEMINI_API_KEY=...
```

For local models (no API keys needed):
```bash
pip install 'keep-skill[local]'   # macOS Apple Silicon optimized
```

See [docs/QUICKSTART.md](docs/QUICKSTART.md) for all provider options.

---

## Quick Start

```bash
# Index URLs, files, and notes (store auto-initializes on first use)
keep put https://inguz.substack.com/p/keep -t topic=practice
keep put "file://$(keep config tool)/docs/library/impermanence_verse.txt" -t type=teaching
keep put "Token refresh needs clock sync" -t topic=auth

# 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 list --tag project=myapp          # Find by tag
keep find "auth" -t topic=auth         # Cross-project topic search
keep list --tags=                      # List all tag keys

# Current intentions
keep now                               # Show what you're working on
keep now "Fixing login bug"            # Update intentions
```

### 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, async 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)

---

## Background

Why build memory for AI agents? What does "reflective practice" mean here?

I wrote a story: **[Wisdom, or Prompt-Engineering?](https://inguz.substack.com/p/keep)**

---

## 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:**
- Before acting, use `keep` to reflect on the context.
- Notice breakdowns — when assumptions surface, index them.
- After acting, use `keep` to save your context and intentions.
- Periodically, run `keep reflect` for a deep, structured reflection.

See **[SKILL.md](SKILL.md)** for the full practice guide.

---

## 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.
