Metadata-Version: 2.4
Name: hybrid-memory
Version: 0.1.0
Summary: Hybrid search memory for AI agents — SQLite FTS5 + Ollama vector embeddings
Author-email: Alex Chen <alex.chen31337@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/clawinfra/hybrid-memory
Project-URL: Repository, https://github.com/clawinfra/hybrid-memory
Keywords: memory,search,fts5,embeddings,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"

# Hybrid Search Memory

Keyword (BM25) + vector (cosine similarity) search over memory files and workspace documents.

## Usage

```bash
# Search (hybrid mode by default — falls back to keyword-only if Ollama is down)
uv run python skills/hybrid-memory/scripts/hybrid_cli.py search "query text"
uv run python skills/hybrid-memory/scripts/hybrid_cli.py search "query" --mode keyword
uv run python skills/hybrid-memory/scripts/hybrid_cli.py search "query" --mode vector

# Ingest all memory files + TOOLS.md/MEMORY.md/AGENTS.md
uv run python skills/hybrid-memory/scripts/hybrid_cli.py ingest-memory

# Ingest a directory
uv run python skills/hybrid-memory/scripts/hybrid_cli.py ingest --path memory/ --pattern "*.md"
uv run python skills/hybrid-memory/scripts/hybrid_cli.py ingest --path memory/ --incremental

# Store a single document
uv run python skills/hybrid-memory/scripts/hybrid_cli.py store --doc-id ID --text "content"
uv run python skills/hybrid-memory/scripts/hybrid_cli.py store --doc-id ID --file path/to/file.md

# Other
uv run python skills/hybrid-memory/scripts/hybrid_cli.py delete --doc-id ID
uv run python skills/hybrid-memory/scripts/hybrid_cli.py reindex
uv run python skills/hybrid-memory/scripts/hybrid_cli.py stats
```

## When to Use

- **Hybrid search**: exact keyword matches + semantic similarity. Best for credential lookups, config values, specific terms.
- **Tiered memory**: LLM-powered tree navigation. Best for broad semantic questions, "what happened last week".

Use hybrid search first (fast, precise), fall back to tiered memory if results are insufficient.

## Architecture

- **Chunker**: Markdown-aware splitting with heading context, configurable size/overlap
- **FTS5**: SQLite full-text search with BM25 ranking
- **Vector**: Ollama `nomic-embed-text` embeddings + cosine similarity
- **Merger**: Weighted combination (keyword=0.3, vector=0.7), normalization, deduplication

Gracefully degrades to keyword-only when Ollama is unavailable.

## Config

Edit `config.json` or pass CLI flags. DB stored in `data/hybrid_search.db`.
