# memory-search

> Hybrid semantic + keyword search across memory files using BM25 for keyword matching and OpenAI embeddings for semantic reranking.

- Author: Nick
- Repository: NickGalindo-yuno/ai-assistant
- Version: 20260207044228
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/NickGalindo-yuno/ai-assistant
- Web: https://mule.run/skillshub/@@NickGalindo-yuno/ai-assistant~memory-search:20260207044228

---

# Memory Search Skill

Hybrid semantic + keyword search across memory files using BM25 for keyword matching and OpenAI embeddings for semantic reranking.

## Requirements

- `OPENAI_API_KEY` environment variable (for embeddings)
- Python 3 with dependencies from `requirements.txt`

## Usage

### Search

Search your memories for relevant content:

```bash
python3 ~/.openclaw/skills/memory-search/memory_search.py search "your query here"
```

Example:
```bash
python3 ~/.openclaw/skills/memory-search/memory_search.py search "deployment process"
```

### Index

Rebuild the embeddings index (usually automatic):

```bash
python3 ~/.openclaw/skills/memory-search/memory_search.py index
```

Force full reindex:
```bash
python3 ~/.openclaw/skills/memory-search/memory_search.py index --force
```

### List

Show indexed files and their status:

```bash
python3 ~/.openclaw/skills/memory-search/memory_search.py list
```

## How It Works

1. **Chunking**: Splits markdown files by H2 headers into chunks
2. **BM25 Keyword Search**: Fast initial ranking based on keyword matches
3. **Embedding Rerank**: Uses OpenAI embeddings to rerank top candidates
4. **Hybrid Scoring**: Combines BM25 (30%) and embedding similarity (70%)

## Indexed Files

The skill indexes:
- `MEMORY.md` - Long-term curated facts
- `memory/*.md` - All markdown files in the memory directory

## Configuration

Edit the constants in `memory_search.py` to customize:

| Constant | Default | Description |
|----------|---------|-------------|
| `EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI embedding model |
| `BM25_WEIGHT` | `0.3` | Weight for keyword matching |
| `EMBEDDING_WEIGHT` | `0.7` | Weight for semantic similarity |
| `TOP_K_BM25` | `20` | Candidates from keyword search |
| `TOP_K_RESULTS` | `5` | Final results returned |
| `MAX_CHUNK_CHARS` | `2000` | Max characters per chunk |

## Auto-Indexing

The index is automatically updated when:
- Files are modified (detected via MD5 hash)
- New files are added to the memory directory
- A search is performed and stale files are detected

## Index Storage

The index is stored at `skills/memory-search/index.json` and is gitignored (regenerated as needed).

## Troubleshooting

**No results found:**
- Check that memory files exist and contain content
- Verify `OPENAI_API_KEY` is set
- Try rebuilding the index with `--force`

**API errors:**
- Verify your OpenAI API key is valid
- Check for rate limiting
- Ensure network connectivity

**Stale results:**
- Run `memory_search.py list` to check file status
- Rebuild index if files show as STALE