106 lines
4.1 KiB
Markdown
Executable File
106 lines
4.1 KiB
Markdown
Executable File
# Ollama Chat Plugin for Obsidian
|
||
|
||
A plugin that integrates Ollama with Obsidian to create a chat interface that can access your vault content.
|
||
|
||
## Features
|
||
|
||
- Chat with Ollama models directly in Obsidian
|
||
- Vault context search — the assistant can reference your notes
|
||
- Tool integration — create files based on chat responses
|
||
- Streaming responses
|
||
- Semantic response cache — repeated or similar queries are answered instantly without hitting the model (requires ChromaDB)
|
||
- Customisable model, URL, and cache settings
|
||
|
||
## Installation
|
||
|
||
1. Install the plugin via Obsidian's community plugins
|
||
2. Make sure you have Ollama installed and running
|
||
|
||
## Setup
|
||
|
||
### Required
|
||
|
||
1. **Install Ollama**: Follow the instructions at [ollama.ai](https://ollama.ai)
|
||
2. **Start Ollama**: `ollama serve`
|
||
3. **Pull a chat model**: `ollama pull llama3` (or any other model you prefer)
|
||
|
||
### Optional — Semantic Cache
|
||
|
||
The semantic cache stores responses in a local [ChromaDB](https://www.trychroma.com) vector database. When you ask a question that is semantically similar to one already cached, the stored answer is returned immediately instead of calling the model.
|
||
|
||
1. **Install ChromaDB**:
|
||
```bash
|
||
pip install chromadb
|
||
```
|
||
2. **Start ChromaDB**:
|
||
```bash
|
||
chroma run --host localhost --port 8000
|
||
```
|
||
3. **Pull an embedding model** (used to generate vectors for cache lookups):
|
||
```bash
|
||
ollama pull nomic-embed-text
|
||
```
|
||
4. Enable the cache in the plugin settings and configure the ChromaDB URL.
|
||
|
||
## Configuration
|
||
|
||
Open **Settings → Ollama Chat** to configure the plugin.
|
||
|
||
| Setting | Default | Description |
|
||
|---------|---------|-------------|
|
||
| Ollama URL | `http://localhost:11434` | Base URL of your Ollama instance |
|
||
| Model | `llama3` | Model used for chat responses |
|
||
| Enable Semantic Cache | Off | Cache responses for fast repeated queries |
|
||
| ChromaDB URL | `http://localhost:8000` | URL of your running ChromaDB instance |
|
||
| Cache Embedding Model | `nomic-embed-text` | Ollama model used to generate cache embeddings |
|
||
| Cache Similarity Threshold | `0.85` | Minimum cosine similarity (0–1) for a cache hit — higher values require closer matches |
|
||
| Clear Semantic Cache | — | Button to wipe all cached responses from ChromaDB |
|
||
|
||
## Usage
|
||
|
||
1. Click the ribbon icon to open the chat view
|
||
2. Type your message in the input box
|
||
3. Press **Enter** or click **Send** to send your message
|
||
4. Press **Shift+Enter** to insert a line break
|
||
5. Click **New Chat** to start a fresh conversation
|
||
|
||
## Semantic Cache Behaviour
|
||
|
||
- The cache is **bypassed** when tool calls are involved (e.g. file creation), since those requests have side effects.
|
||
- Responses are stored against the last user message in the conversation. If a new query is sufficiently similar (above the configured threshold), the cached response is returned.
|
||
- Re-asking the same question updates the existing cache entry rather than creating a duplicate.
|
||
- Use the **Clear Semantic Cache** button in settings to remove all stored responses (for example after switching embedding models).
|
||
|
||
## Supported Models
|
||
|
||
Any model supported by Ollama should work, including:
|
||
|
||
- `llama3`
|
||
- `llama2`
|
||
- `mistral`
|
||
- `codellama`
|
||
- and many more — see [ollama.com/library](https://ollama.com/library)
|
||
|
||
## Development
|
||
|
||
```bash
|
||
npm install
|
||
npm run build
|
||
npm test
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
| Symptom | Likely cause | Fix |
|
||
|---------|-------------|-----|
|
||
| Cannot connect to Ollama | Ollama is not running | Run `ollama serve` |
|
||
| Model not found | Model not pulled | Run `ollama pull <model>` |
|
||
| Semantic cache unavailable (notice shown) | ChromaDB is not running, or the ChromaDB URL is wrong | Start ChromaDB (`chroma run`) and verify the URL in settings |
|
||
| Cache always misses | Similarity threshold is too high, or the embedding model was changed | Lower the threshold or click **Clear Semantic Cache** and let the cache rebuild |
|
||
| Slow first response after enabling cache | Embedding model not yet pulled | Run `ollama pull nomic-embed-text` (or the model you configured) |
|
||
| Permission issues | Vault write permissions | Check that your Obsidian vault has proper write permissions |
|
||
|
||
## License
|
||
|
||
MIT
|