zettel-link

# Zettel Link Skill

This skill provides a suite of idempotent Python scripts to embed, search, and link notes in an Obsidian vault using semantic similarity. All scripts live in `scripts/` and support multiple embedding providers.

The skill should be triggered when the user wants to search notes, retrieve notes, or discover connections between notes.

If the search directory is indexed with embeddings, the skill should prompt the user if they want to create new embeddings.

## Dependencies

- uv 0.10.0+
- Python 3.10+
- One of the following embedding providers:
  - [Ollama](https://ollama.com) with `mxbai-embed-large` (local, default)
  - [OpenAI API](https://platform.openai.com/) with `text-embedding-3-small`
  - [Google Gemini API](https://ai.google.dev/) with `text-embedding-004`

## Overview of Commands

- `uv run scripts/config.py`: Configure the embedding model and other settings.
- `uv run scripts/embed.py`: Embed notes and cache to `.embeddings/embeddings.json`
- `uv run scripts/search.py`: Semantic search over embedded notes
- `uv run scripts/link.py`: Discover semantic connections, output to `.embeddings/links.json`

## Workflow

### Step 0 — Setup and Config

If the `config/config.json` file does not exist, create it:

```bash
uv run scripts/config.py
```

This creates `config/config.json` with defaults:

```json
{
    "model": "mxbai-embed-large",
    "provider": {
        "name": "ollama",
        "url": "http://localhost:11434"
    },
    "max_input_length": 8192,
    "cache_dir": ".embeddings",
    "default_threshold": 0.65,
    "top_k": 5,
    "skip_dirs": [".obsidian", ".trash", ".embeddings", "Spaces", "templates"],
    "skip_files": ["CLAUDE.md", "Vault.md", "Dashboard.md", "templates.md"]
}
```

To use a remote provider:

```bash
# OpenAI
uv run scripts/config.py --provider openai

# Gemini
uv run scripts/config.py --provider gemini

# Custom model
uv run scripts/config.py --provider openai --model text-embedding-3-large
```

To adjust tuning p...

# zettel-link

A suite of Python scripts for semantically searching and linking notes in an Obsidian directory based on embedding similarity.

## Scripts

```
scripts/
├── config.py # Configure the embedding model and provider
├── embed.py  # Embed notes, cached to .embeddings/embeddings.json
├── search.py # Semantic search over embedded notes
└── link.py   # All-pairs similarity → .embeddings/links.json
```

## Quick Start

Install it via npx skills command:

```bash
npx skills install https://github.com/hxy9243/skills/blob/main/zettel-link/
```

## Requirements

- uv 0.10.0+
- Python 3.10+
- One of:
  - [Ollama](https://ollama.com) with `mxbai-embed-large` (local, default)
  - [OpenAI API](https://platform.openai.com/) with `text-embedding-3-small`
  - [Google Gemini API](https://ai.google.dev/) with `text-embedding-004`

## Supported Providers

| Provider | Default Model            | API Key Env     |
|----------|--------------------------|-----------------|
| ollama   | mxbai-embed-large        | *(none)*        |
| openai   | text-embedding-3-small   | OPENAI_API_KEY  |
| gemini   | text-embedding-004       | GEMINI_API_KEY  |

## Security

To prevent suspicious environment scanning, `zettel-link` supports loading API keys from a local `.env` file within the skill directory.

1. Create a `.env` file in the skill root.
2. Add your keys:
   ```bash
   OPENAI_API_KEY=your_key_here
   GEMINI_API_KEY=your_key_here
   ```

The script will check the environment first, then fallback to the `.env` file.


## Idempotency

All scripts are safe to re-run:
- `embed.py` uses mtime-based caching — only re-embeds changed notes
- `search.py` and `link.py` are read-only against the cache