fegger/obsidian_ollama
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
fegger
2026-05-07 21:36:39 +02:00
committed by Florian Egger
parent ae16396a7a
commit e6d791a655
1 changed files with 88 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -76
View File
@@ -1,58 +1,75 @@
# Ollama Chat Plugin for Obsidian
# Obsidian Ollama Plugin
A plugin that integrates [Ollama](https://ollama.ai) with [Obsidian](https://obsidian.md) to create a chat interface that can access your vault content contextually.
A plugin that integrates [Ollama](https://ollama.ai) with Obsidian, allowing you to chat with local AI models, search your vault context, and use AI tools like creating files.
## Features
- **Chat with local AI models** — Interact with Ollama models directly in Obsidian's sidebar
- **Vault context search** — The assistant automatically searches your notes using weighted scoring (headings, frontmatter titles/tags, content)
- **Tool integration** — AI can create files in your vault via the `create_file` tool
- **Streaming responses** — Real-time token streaming for a responsive chat experience
- **Configurable settings** — Customize model, URL, search limits, and message history
- 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
### From Source
1. Clone this repository into your Obsidian vault's `.obsidian/plugins/` folder:
```bash
cd .obsidian/plugins
git clone <repo-url> obsidian-ollama
cd obsidian-ollama
npm install
npm run build
```
2. Enable the plugin in Obsidian: Settings → Community plugins → Ollama Plugin
1. Install the plugin via Obsidian's community plugins
2. Make sure you have Ollama installed and running
## Prerequisites
1. **Install Ollama**: Follow the instructions at [ollama.ai](https://ollama.ai)
2. **Start Ollama**: `ollama serve`
3. **Pull a model**: `ollama pull llama3` (or any model you prefer)
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 Plugin to configure:
Open **Settings → Ollama Chat** to configure the plugin.
| Setting | Default | Description |
|---------|---------|-------------|
| Ollama URL | `http://localhost:11434` | Your Ollama instance URL |
| Model | `llama3` | Model to use for chat |
### Internal Settings
| Setting | Default | Description |
|---------|---------|-------------|
| Vault Search Limit | `3` | Max notes returned for context |
| Max Message History | `50` | Messages kept in conversation context |
|-----|- -- ----|-------|
| 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 chat icon in the left ribbon to open the chat view
2. Type your message and press **Enter** or click **Send**
3. Click **New Chat** to start a fresh conversation
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
### Vault Context
## 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).
## Vault Context
When you send a message, the plugin automatically searches your vault for relevant notes and includes them as context. The search uses weighted scoring:
@@ -62,7 +79,7 @@ When you send a message, the plugin automatically searches your vault for releva
- **First paragraph** — 1.5x weight
- **General content** — 1x weight
### Tools
## Tools
The plugin exposes a `create_file` tool that allows the AI to create new markdown files in your vault. Paths are validated for safety (no `.obsidian`/`.git` access, no path traversal).
@@ -70,55 +87,30 @@ The plugin exposes a `create_file` tool that allows the AI to create new markdow
Any Ollama-supported model works. Popular choices:
| Model | Best For |
|-------|----------|
| `llama3` | General chat |
| `mistral` | Fast responses |
| `codellama` | Code assistance |
| `gemma` | Lightweight local use |
- `llama3`
- `llama2`
- `mistral`
- `codellama`
- and many more — see [ollama.com/library](https://ollama.com/library)
## Development
```bash
npm install # Install dependencies
npm run build # Compile TypeScript
npm run watch # Watch mode for development
npm test # Run tests (Jest)
npm run lint # Lint with ESLint
npm run format # Format with Prettier
```
### Project Structure
```
src/
├── main.ts # Plugin entry point and settings
├── chat-view.ts # Chat UI and message handling
├── ollama-client.ts # Ollama API communication
├── vault-indexer.ts # Vault search and scoring
├── tool-executor.ts # Tool execution (create_file)
├── error-handler.ts # Centralized error handling
├── utils.ts # Validation and logging utilities
├── types.ts # TypeScript type definitions
└── constants.ts # Default configuration
```
### Testing
The project includes tests for all major components. Run with:
```bash
npm install
npm run build
npm test
```
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Connection refused | Ensure Ollama is running (`ollama serve`) |
| Model not found | Pull the model first (`ollama pull <model>`) |
| Permission errors | Check vault write permissions |
| Empty responses | Try a different model or check Ollama logs |
| 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 |
## Security
@@ -129,4 +121,24 @@ npm test
## License
MIT
MIT License
Copyright (c) 2024 Flo Egger
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.